doc/user_guide/parameters.tex

%!TEX root=./user_guide.tex
\chapter{Parameters}\label{chap:parameters}

\section{Usage}
{\tt wannier90.x} can be run in parallel using MPI libraries to
reduce the computation time.

For serial execution use: {\tt wannier90.x [-pp] [seedname]}

\begin{itemize}
\item{ {\tt seedname}: If a seedname string is given the code will read its input
from a file {\tt seedname.win}. The default value is {\tt wannier}. One can also equivalently provide the string
  {\tt seedname.win} instead of  {\tt seedname}.}
\item { {\tt -pp}: This optional flag tells the code to generate
a list of the required overlaps and then exit.
This information is written to the file {\tt seedname.nnkp}.}
\end{itemize}

For parallel execution use: {\tt mpirun -np NUMPROCS wannier90.x [-pp] [seedname]}

\begin{itemize} \item
{\tt NUMPROCS}: substitute with the number of processors that you want
to use.
\end{itemize}

Note that the {\tt mpirun} command and command-line flags may be
different in your MPI implementation: read your MPI manual or ask your
computer administrator.

Note also that this requires that the {\tt wannier90.x} executable has been
compiled in its parallel version (follow the instructions in the file
{\tt README.install} in the main directory of the wannier90
distribution) and
that the MPI libraries and binaries are installed and correctly
configured on your machine.


\section{{\tt seedname.win} File\label{sec:seednamefile}}
The \wannier\ input file {\tt seedname.win} has a flexible free-form
structure.

The ordering of the keywords is not significant. Case is ignored (so
\verb#num_bands# is the same as \verb#Num_Bands#). Characters after !, or \#
are treated as comments. Most keywords have a default value that is
used unless the keyword is given in {\tt seedname.win}. Keywords can be set
in any of the following ways
{\tt
\begin{quote}
num\_wann   4

num\_wann = 4

num\_wann : 4
\end{quote} }
A logical keyword can be set to {\tt true} using any of the following
strings: {\tt T}, {\tt true}, {\tt .true.}.

For further examples see Section~\ref{winfile} and the the \wannier\ Tutorial.

\section{Keyword List}
\label{parameter_data}

\begin{table}[b]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{System Parameters} \\
\hline
{\sc num\_wann }   & I & Number of WF \\
{\sc num\_bands }   & I & Number of bands passed to the code \\
{\sc unit\_cell\_cart }   & P & Unit cell vectors in Cartesian coordinates \\
{\sc atoms\_cart }*   & P & Positions of atoms in Cartesian coordinates \\
{\sc atoms\_frac }*   & R & Positions of atoms in fractional
coordinates with respect to the lattice vectors \\
{\sc mp\_grid }   & I & Dimensions of the Monkhorst-Pack grid of
k-points \\
%{\sc mp\_grid\_automatic }**   & L & Determine the k-point automatically \\
{\sc kpoints }   & R & List of k-points in the Monkhorst-Pack grid \\
{\sc gamma\_only} & L & Wavefunctions from underlying ab initio
calculation are manifestly real \\
{\sc spinors} & L & WF are spinors \\
{\sc shell\_list }   & I & Which shells to use in finite difference formula \\
{\sc search\_shells }   & I & The number of shells to search when
determining finite difference formula \\
{\sc skip\_B1\_tests }   & L & Check the condition B1 of Ref.~\cite{marzari-prb97}  \\
{\sc nnkpts} & I & Explicit list of nearest-neighbour k-points.\\
{\sc kmesh\_tol } & R & The tolerance to control if two kpoint belong to the same shell \\
\hline
\end{tabular}
\caption[Parameter file keywords controlling system parameters.]
{{\tt seedname.win} file keywords defining the system.  Argument types
are represented by, I for a integer, R for a real number, P for a
physical value, L for a logical value and S for a text string.\\
 {\footnotesize
* {\sc atoms\_cart } and  {\sc atoms\_frac } may not both be defined in
the same input file. }}
\label{parameter_keywords1}
\end{center}
\end{table}

\clearpage

\begin{table}
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{Job Control} \\
\hline
{\sc postproc\_setup }   & L & To output the {\tt seedname.nnkp} file \\
%{\sc cp\_pp }   & L & CP code post-processing \\
%{\sc calc\_only\_a }   & L & Only recalculate the projections \\
{\sc exclude\_bands }   & I & List of bands to exclude from the calculation \\
{\sc select\_projections }   & I & List of projections to use in Wannierisation \\
{\sc auto\_projections } & L & To automatically generate initial projections \\
{\sc restart }   & S & Restart from checkpoint file \\
{\sc iprint }   & I & Output verbosity level \\
{\sc length\_unit }   & S & System of units to output lengths \\
{\sc wvfn\_formatted }   & L & Read the wavefunctions from a  (un)formatted file  \\
{\sc spin }   & S & Which spin channel to read \\
{\sc devel\_flag }   & S & Flag for development use \\
{\sc timing\_level } & I & Determines amount of timing information
written to output \\
{\sc optimisation } & I & Optimisation level \\
{\sc translate\_home\_cell } & L & To translate final Wannier centres
to home unit cell when writing xyz file\\
{\sc write\_xyz }  & L & To write atomic positions and final centres in xyz file format \\
{\sc write\_vdw\_data }  & L & To write data for futher processing by w90vdw utility\\
{\sc write\_hr\_diag }  & L & To write the diagonal elements of
the Hamiltonian in the Wannier basis to seedname.wout (in eV)\\
\hline
\end{tabular}
\caption[win file keywords.]
{{\tt seedname.win} file keywords defining job control.  Argument types
are represented by, I for a integer, R for a real number, P for a
physical value, L for a logical value and S for a text string. {\sc
  translate\_home\_cell } only relevant if {\sc write\_xyz} is
\texttt{.true.}}
\label{parameter_keywords2}
\end{center}
\end{table}


\begin{table}
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{Disentanglement Parameters} \\
\hline
{\sc dis\_win\_min }   & P & Bottom of the outer energy window \\
{\sc dis\_win\_max }   & P & Top of the outer energy window \\
{\sc dis\_froz\_min }   & P & Bottom of the inner (frozen) energy window \\
{\sc dis\_froz\_max }   & P & Top of the inner (frozen) energy window \\
{\sc dis\_num\_iter }   & I & Number of iterations for the minimisation
of $\omi$ \\
{\sc dis\_mix\_ratio }   & R & Mixing ratio during the minimisation of $\omi$\\
{\sc dis\_conv\_tol }   & R & The convergence tolerance for finding $\omi$ \\
{\sc dis\_conv\_window }   & I & The number of iterations over which
convergence of $\omi$ is assessed. \\
{\sc dis\_spheres\_num }   & I & Number of spheres in k-space where disentaglement is performed\\
{\sc dis\_spheres\_first\_wann }   & I & Index of the first band to be considered a Wannier function \\
{\sc dis\_spheres } & R & List of centres and radii, for disentanglement only in spheres \\
\hline
\end{tabular}
\caption[Parameter file keywords controlling disentanglement parameters.]
{{\tt seedname.win} file keywords controlling the disentanglement.
  Argument types
are represented by, I for a integer, R for a real number, P for a
physical value, L for a logical value and S for a text string.}
\label{parameter_keywords4}
\end{center}
\end{table}


\begin{table}
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{Wannierise Parameters} \\
\hline
{\sc num\_iter }   & I & Number of iterations for the minimisation
of $\Omega$ \\
{\sc num\_cg\_steps }   & I & During the minimisation
of $\Omega$ the number of Conjugate Gradient steps before resetting to
Steepest Descents \\
{\sc conv\_window }   & I & The number of iterations over which
convergence of $\Omega$ is assessed \\
{\sc conv\_tol }   & P & The convergence tolerance for finding $\Omega$  \\
{\sc precond }   & L & Use preconditioning \\
{\sc conv\_noise\_amp} & R & The amplitude of random noise applied
towards end of minimisation procedure \\
{\sc conv\_noise\_num} & I & The number of times random noise is
applied \\
{\sc num\_dump\_cycles }   & I & Control frequency of check-pointing \\
{\sc num\_print\_cycles }   & I & Control frequency of printing \\
{\sc write\_r2mn }   & L & Write matrix elements of $r^2$ between
WF to file \\
{\sc guiding\_centres }   & L & Use guiding centres \\
{\sc num\_guide\_cycles }   & I & Frequency of guiding centres \\
{\sc num\_no\_guide\_iter }   & I & The number of iterations
after which guiding centres are used\\
{\sc trial\_step }*   & R & The trial step length for the parabolic
line search during the minimisation
of $\Omega$\\
{\sc fixed\_step }*   & R & The fixed step length to take during the minimisation
of $\Omega$, instead of doing a parabolic line search \\
{\sc use\_bloch\_phases }**   & L & To use phases for initial projections \\
{\sc site\_symmetry}***   & L & To construct symmetry-adapted Wannier functions  \\
{\sc  symmetrize\_eps}***   & R &  The convergence tolerance used in the symmetry-adapted mode \\
{\sc slwf\_num} & I & The number of objective WFs for selective localization \\
{\sc slwf\_constrain} & L & Whether to constrain the centres of the objective WFs \\
{\sc slwf\_lambda} & R & Value of the Lagrange multiplier for constraining the objective WFs \\
{\sc slwf\_centres} & P & The centres to which the objective WFs are to be constrained \\
\hline
\end{tabular}
\caption[Parameter file keywords controlling the Wannierise routine.]
{{\tt seedname.win} file keywords controlling the wannierisation.
  Argument types
are represented by, I for a integer, R for a real number, P for a
physical value, L for a logical value and S for a text string.
{\footnotesize
* {\sc fixed\_step } and  {\sc trial\_step } may not both be defined in
the same input file. **Cannot be used in conjunction with disentanglement.
***Cannot be used in conjunction with the inner (frozen) energy window.}}
\label{parameter_keywords5}
\end{center}
\end{table}


\begin{longtable}{|c|c|p{6cm}|}
%\begin{center}
%\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{Plot Parameters} \\
  \hline
  {\sc wannier\_plot }   & L & Plot the WF \\
  {\sc wannier\_plot\_list } & I & List of WF to plot \\
  {\sc wannier\_plot\_supercell }   & I & Size of the supercell for
  plotting the WF \\
  {\sc wannier\_plot\_format }   & S & File format in which to plot the
  WF \\
  {\sc wannier\_plot\_mode }   & S & Mode in which to plot the
  WF, molecule or crystal \\
  {\sc wannier\_plot\_radius } & R & Cut-off radius of WF* \\
  {\sc wannier\_plot\_scale } & R & Scaling parameter for cube files \\
  {\sc wannier\_plot\_spinor\_mode } & S& Quantity to plot for spinor WF\\
  {\sc wannier\_plot\_spinor\_phase } & L& Include the ``phase'' when plotting spinor WF\\
  {\sc bands\_plot }   & L & Plot interpolated band structure \\
  {\sc kpoint\_path }   & P & K-point path for the interpolated band structure  \\
  {\sc bands\_num\_points }   & I & Number of points along the first
  section of the k-point path \\
  {\sc bands\_plot\_format }   & S & File format in which to plot the
  interpolated bands \\
  {\sc bands\_plot\_project } & I & WF to project the band structure onto \\
  {\sc bands\_plot\_mode }   & S & Slater-Koster type interpolation or
  Hamiltonian cut-off \\
  {\sc bands\_plot\_dim } & I & Dimension of the system \\
  {\sc fermi\_surface\_plot }   & L & Plot the Fermi surface \\
  {\sc fermi\_surface\_num\_points }   & I & Number of points in the Fermi
  surface plot\\
  {\sc fermi\_energy }   & P & The Fermi energy \\
  {\sc fermi\_energy\_min }   & P & Lower limit of
  the Fermi energy range\\
  {\sc fermi\_energy\_max }   & P & Upper limit of
  the Fermi energy range\\
  {\sc fermi\_energy\_step }   & R & Step for increasing the
Fermi energy in the specified range\\
  {\sc fermi\_surface\_plot\_format }   & S & File format for the Fermi
  surface plot \\
  \old{\sc hr\_plot} & L & \old{This parameter is not used anymore. Use {\sc write\_hr} instead.} \\
  \new{\sc write\_hr} & L & \new{Write the Hamiltonian in the WF basis} \\
  \new{\sc write\_rmn } & L & \new{Write the position operator in the WF basis} \\
  \new{\sc write\_bvec } & L & \new{Write to file the matrix elements of the bvectors and their weights} \\
\new{\sc write\_tb }  & L & \new{Write lattice vectors,
Hamiltonian, and position operator in WF basis} \\
  {\sc hr\_cutoff} & P &  Cut-off for the absolute value of the Hamiltonian \\
  {\sc dist\_cutoff} & P & Cut-off for the distance between WF \\
  {\sc dist\_cutoff\_mode} & S & Dimension in which the distance between WF
  is calculated \\
  {\sc translation\_centre\_frac } & R & Centre of the unit cell to which
  final WF are translated \\
  \new{\sc use\_ws\_distance } & L & \new{Improve interpolation using minimum distance between WFs, see Chap.~\ref{chap:interpolation}} \\
  \new{\sc ws\_distance\_tol } & R & \new{Absolute tolerance for the distance to equivalent positions.} \\
  \new{\sc ws\_search\_size } & I & \new{Maximum extension in each direction of the super-cell of the Born-von Karmann cell to search for points inside the Wigner-Seitz cell}\\
  \new{\sc write\_u\_matrices } & L & \new{Write $\mathbf{U}^{(\mathbf{k})}$ and $\mathbf{U}^{\mathrm{dis}(\mathbf{k})}$ matrices to files} \\
%{\sc slice\_plot }   & L & Plot the Wannier Functions along a slice \\
%{\sc slice\_coord }   & P & Coordinates of the slice \\
%{\sc slice\_num\_points }   & I & Number of points in the slice plot \\
%{\sc slice\_plot\_format }   & S & File format of the slice plot \\
%{\sc dos\_plot }   & L & Plot the interpolated density of states \\
%{\sc dos\_num\_points }   & I & Number of points in the dos plot \\
%{\sc dos\_energy\_step }   & P & Size of the energy step in the dos plot \\
%{\sc dos\_gaussian\_width }   & P & Width of the convolving gaussian
%smearing for the dos plot \\
%{\sc dos\_plot\_format }   & S & Format of the dos plot \\
\hline
%\end{tabular}
\caption[Parameter file keywords controlling plotting.]
{{\tt seedname.win} file keywords controlling the  plotting.  Argument types
are represented by, I for a integer, R for a real number, P for a
physical value, L for a logical value and S for a text string. * Only
applies when {\sc wannier\_plot\_format} is {\tt cube}.}
\label{parameter_keywords6}
%\end{center}
\end{longtable}


\begin{table}
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{Transport Parameters} \\
\hline
{\sc transport}   & L & Calculate quantum conductance and density of states \\
{\sc transport\_mode }  & S & Bulk or left-lead\_conductor\_right-lead calculation \\
{\sc tran\_win\_min } & P &  Bottom of the energy window for transport calculation\\
{\sc tran\_win\_max } & P &  Top of the energy window for transport calculation\\
{\sc tran\_energy\_step } & R & Sampling interval of the energy values \\
{\sc fermi\_energy } & R & The Fermi energy \\
{\sc tran\_num\_bb } & I & Size of a bulk Hamiltonian \\
{\sc tran\_num\_ll } & I & Size of a left-lead Hamiltonian \\
{\sc tran\_num\_rr } & I & Size of a right-lead Hamiltonian \\
{\sc tran\_num\_cc } & I & Size of a conductor Hamiltonian \\
{\sc tran\_num\_lc } & I & Number of columns in a left-lead\_conductor Hamiltonian \\
{\sc tran\_num\_cr } & I & Number of rows in a conductor\_right-lead Hamiltonian \\
{\sc tran\_num\_cell\_ll } & I & Number of unit cells in PL of left lead \\
{\sc tran\_num\_cell\_rr } & I & Number of unit cells in PL of right lead \\
{\sc tran\_num\_bandc } & I & Half-bandwidth+1 of a band-diagonal conductor Hamiltonian \\
{\sc tran\_write\_ht } & L & Write the Hamiltonian for transport calculation \\
{\sc tran\_read\_ht } & L & Read the Hamiltonian for transport calculation \\
{\sc tran\_use\_same\_lead } & L & Left and right leads are the same \\
{\sc tran\_group\_threshold } & R & Distance that determines the grouping of WFs \\
{\sc hr\_cutoff} & P &  Cut-off for the absolute value of the Hamiltonian \\
{\sc dist\_cutoff} & P & Cut-off for the distance between WF \\
{\sc dist\_cutoff\_mode} & S & Dimension in which the distance between WF
is calculated \\
{\sc one\_dim\_axis} & S &  Extended direction for a one-dimensional system \\
{\sc translation\_centre\_frac } & R & Centre of the unit cell to which
final WF are translated \\
\hline
\end{tabular}
\caption[Parameter file keywords controlling transport.]
{{\tt seedname.win} file keywords controlling transport. Argument types
are represented by, I for a integer, R for a real number, P for a
physical value, L for a logical value and S for a text string.}
\label{parameter_keywords7}
\end{center}
\end{table}

\clearpage


\section{System}

\subsection[num\_wann]{\tt integer :: num\_wann}
Number of WF to be found.

No default.

\subsection[num\_bands]{\tt integer :: num\_bands}

Total number of bands passed to the code in the {\tt seedname.mmn} file.

Default \verb#num_bands#=\verb#num_wann#

\subsection[Cell Lattice Vectors]{Cell Lattice Vectors}

The cell lattice vectors should be specified in Cartesian coordinates.


\noindent \verb#begin unit_cell_cart# \\
\verb#[units]#
$$
\begin{array}{ccc}
A_{1x} & A_{1y} & A_{1z} \\
A_{2x} & A_{2y} & A_{2z} \\
A_{3x} & A_{3y} & A_{3z}
\end{array}
$$
\verb#end unit_cell_cart#

Here $A_{1x}$ is the $x$-component of the first lattice vector $\mathbf{A}_1$,
$A_{2y}$ is the $y$-component of the second lattice vector $\mathbf{A}_2$, etc.

\verb#[units]# specifies the units in which the lattice vectors are
defined: either \verb#Bohr# or \verb#Ang#.

The default value is \verb#Ang#.


\subsection[Ionic Positions]{Ionic Positions}

The ionic positions may be specified in fractional coordinates relative
to the lattice vectors of the unit cell, or in absolute Cartesian coordinates.
Only one of \verb#atoms_cart# and \verb#atoms_frac# may be given in the input
file.


\subsubsection{Cartesian coordinates}

\noindent \verb#begin atoms_cart# \\
\verb#[units]#
$$
\begin{array}{cccc}
P  & R^{P}_{x} & R^{P}_{y} & R^{P}_{z} \\
Q  & R^{Q}_{x} & R^{Q}_{y} & R^{Q}_{z} \\
\vdots
\end{array}
$$
\verb#end atoms_cart#


The first entry on a line is the atomic symbol. The next three entries
are the atom's position $\mathbf{R}=(R_x , R_y, R_z)$ in Cartesian
coordinates. The first line of the block, \verb#[units]#, specifies
the units in which the coordinates are given and can be either
\verb#bohr# or \verb#ang#. If not present, the default is \verb#ang#.

\subsubsection{Fractional coordinates}

\noindent \verb#begin atoms_frac#
$$
\begin{array}{cccc}
P  & F^{P}_{1} & F^{P}_{2} & F^{P}_{3} \\
Q  & F^{Q}_{1} & F^{Q}_{2} & F^{Q}_{3} \\
\vdots
\end{array}
$$
\verb#end atoms_frac#

The first entry on a line is the atomic symbol. The next three entries
are the atom's position in fractional coordinates $\mathbf{F} = F_1
\mathbf{A}_{1} + F_2 \mathbf{A}_{2} + F_3 \mathbf{A}_{3}$
relative to the cell lattice vectors $\mathbf{A}_i$, $i\in [1,3]$.

\subsection[mp\_grid]{\tt integer, dimension :: mp\_grid(3)}
Dimensions of the regular (Monkhorst-Pack) k-point mesh. For example,
for a $2\times2\times2$ grid:

\verb#mp_grid : 2  2  2#

No default.


%
%\subsection[mp\_grid\_automatic]{\tt logical :: mp\_grid\_automatic}
%\red{Not yet implemented}
%
%If
%$\verb#mp_grid_automatic#=\verb#true#$
%then a "standard" Monkhorst-Pack grid over the interval (0,1] with dimensions \verb#mp_grid#
%will be used. The k-points will be assumed to be numbered such that the
%loop over the x is fastest eg
%
%$$
%\begin{array}{cccc}
%Kpoint 1 &  0.0 & 0.0& 0.0 \\
%Kpoint 2 & 0.25 &0.0 & 0.0 \\
%Kpoint 3 & 0.50 &0.0 & 0.0 \\
%Kpoint 4 & 0.75 &0.0 & 0.0 \\
%Kpoint 5 & 0.0  &0.25& 0.0 \\
%\vdots
%\end{array}
%$$
%
%If $\verb#mp_grid_automatic#=\verb#true#$ then a \verb#kpoint# block must not be present.
%

%{\it This keyword is helpful if one is using a dense MP mesh (eg
%  12x12x12) as it saves typing in a very long list of kpoints}
%
%The default for this keyword is \verb#FALSE#.


\subsection[Kpoints]{K-points}
Each line gives the coordinate $\mathbf{K}=K_1 \mathbf{B}_{1} + K_2
\mathbf{B}_{2} + K_3 \mathbf{B}_3$ of a k-point
in relative (crystallographic) units, i.e., in fractional units with
respect to the primitive reciprocal lattice vectors $\mathbf{B}_{i}$,
$i \in [1,3]$. The position  of each
k-point in this list assigns its numbering; the first k-point is
k-point 1, the second is k-point 2, and so on.


\noindent \verb#begin kpoints# \\
$$
\begin{array}{ccc}
 K^{1}_{1} & K^{1}_{2} & K^{1}_{3} \\
 K^{2}_{1} & K^{2}_{2} & K^{2}_{3} \\
\vdots
\end{array}
$$
\verb#end kpoints#

%If a kpoint list is specified then \verb#mp_grid_automatic# must be
%\verb#FALSE#.

There is no default.

{\bfseries Note}: There is an utility provided with {\tt wannier90},
called {\tt kmesh.pl}, which helps to generate the explicit list of
$k$ points required by {\tt wannier90}. See Sec.~\ref{sec:kmesh}.

\subsection[gamma\_only]{{\tt logical :: gamma\_only}}

If {\tt gamma\_only=true}, then \wannier\ uses a branch of algorithms
for disentanglement and localisation that exploit the fact that the
Bloch eigenstates obtained from the underlying ab initio calculation
are manifestly real. This can be the case when only the $\Gamma$-point
is used to sample the Brillouin zone. The localisation procedure
that is used in the $\Gamma$-only branch is based on the method of
Ref.~\cite{gygi-cpc03}.

The default value is {\tt false}.


\subsection[spinors]{{\tt logical :: spinors}}

If {\tt spinors=true}, then \wannier\
assumes that the WF correspond to singularly occupied spinor states and {\tt num\_elec\_per\_state=1}.

The default value is {\tt false}.

\subsection{Shells}

The MV scheme requires a finite difference expression
for $\nabla_{\bf k}$ defined on a uniform Monkhorst-Pack mesh of
k-points. The vectors $\{{\bf b}\}$ connect each mesh-point ${\bf k}$
  to its nearest neighbours. $N_{\mathrm{sh}}$ shells of neighbours
  are included in the finite-difference formula, with $M_s$ vectors in
  the $s^{\mathrm{th}}$ shell. For $\nabla_{{\bf k}}$ to be correct to
  linear order, we require that the following equation is satisfied
  (Eq.~B1 of Ref.~\cite{marzari-prb97}):
\begin{equation}\label{eq:B1}
\sum_{s}^{N_{\mathrm{sh}}} w_s \sum_i^{M_{\mathrm{s}}}
b_{\alpha}^{i,s} b_{\beta}^{i,s} = \delta_{\alpha\beta}\:,
\end{equation}
where ${\bf b}^{i,s}$, $i\in[1,M_s]$, is the
$i^{\mathrm{th}}$ vector belonging to the $s^{\mathrm{th}}$ shell
with associated weight $w_s$, and $\alpha$ and $\beta$ run over the
three Cartesian indices.


\subsection[shell\_list]{\tt integer :: shell\_list(:)}

\verb#shell_list# is vector listing the shells
to include in the finite difference expression. If this keyword is
absent, the shells are chosen automatically.

\subsection[search\_shells]{\tt integer :: search\_shells}

Specifies the number of shells of neighbours over which to search in
attempting to determine an automatic solution to the B1 condition
Eq.~\ref{eq:B1}. Larger values than the default may be required in special
cases e.g. for very long thin unit cells.

The default value is 36.

\subsection[skip\_B1\_tests]{\tt logical :: skip\_B1\_tests}

If set to \texttt{.true.}, does not check the B1 condition
Eq.~\ref{eq:B1}. This should \emph{only} be used if one knows
why the B1 condition should not be verified. A typical use of this
flag is in conjunction with the Z2PACK code:
\url{http://www.physics.rutgers.edu/z2pack/}.

The default value is \texttt{.false.}.

\subsection[nnkpts]{\tt integer, dimension(:, 5) :: nnkpts}

Specifies the nearest-neighbour k-points which are written to the \texttt{.nnkp} file. This can be used to explicitly specify which overlap matrices should be calculated.

\begin{verbatim}
begin nnkpts
1   2   0  0  0
.
.
end nnkpts
\end{verbatim}

Each nearest neighbour $\mathbf{k + b}$ is given by a line of 5 integers. The first specifies the k-point number \texttt{nkp} of $\mathbf{k}$. The second is the k-point number of the neighbour. The final three integers specify the reciprocal lattice vector which brings the k-point specified by the second integer to $\mathbf{k + b}$.

This format is the same as in the \texttt{.nnkp} file, except that the number of neighbours per k-point is not specified. However, the number of neighbours still needs to be a multiple of the number of k-points.

This input parameter can be used only if \texttt{postproc\_setup = .true.}, and is not intended to be used with a full Wannier90 run. It can be used also if the k-points do not describe a regular mesh.

\subsection[kmesh\_tol]{\tt real(kind=dp) :: kmesh\_tol}

Two kpoints belong to the same shell if the distance between them is
less than {\tt kmesh\_tol}.
Units are Ang.

The default value is 0.000001 Ang.

\section{Projection}

 The projections block defines a set of localised functions used to
 generate an initial guess for the unitary transformations. %The projection block can be specified
%in conjunction with {\tt scdm\_proj=true} (see below). This is only used to read the centres of the projections, which in some cases could help the optimisation if {\tt guiding\_centres=true} is added to the input file.
This data will be written in the {\tt seedname.nnkp} file to be used
by a first-principles code.

\noindent \verb#begin projections# \\
  . \\
  . \\
\verb#end projections#

If \verb#guiding_centres#={\tt true}, then the projection centres are
used as the guiding centres in the Wannierisation routine.

For details see Section~\ref{sec:proj}.

%\section{Constrains on centres}
%
%The constrained centres block defines the target positions, in fractional co-ordinates, for the OWFs whose centres are meant to be constrained.
%
%The block below shows all possible ways of setting the constraints. In particular, assuming $J'=5<J=${\tt num\_wann} :
%
%\noindent \verb#begin centre_constraints# \\
%2 0.0 0.0 0.0 \\
%4 0.25 0.0 0.0 \\
%\verb#end centre_constraints#
%
%\begin{itemize}
%\item The first line sets the constraint for the centre of OWF number 2 (as defined in the projection block) to (0.0,0.0,0.0) in fractional co-ordinates.
%\item The second line sets the constraint for the centre of OWF number 4 (as defined in the projection block) to (0.25,0.0,0.0) in fractional co-ordinates.
%\item The centres of all the other Objective Wannier functions, i.e. 1,3,5, etc. are set to their initial projection centres.
%\end{itemize}

\section{Job Control}

\subsection[postproc\_setup]{\tt logical :: postproc\_setup}
If \verb#postproc_setup#=\verb#true#, then the wannier code will write
 {\tt seedname.nnkp} file and exit.
If \wannier\ is called with the option {\tt -pp}, then
 \verb#postproc_setup# is set to
\verb#true#, over-riding its
value in the {\tt seedname.win} file.

The default value is \verb#false#.


%\subsection[cp\_pp]{\tt logical :: cp\_pp}
%If \verb#cp_pp#=\verb#true# we are using input files from the CP code.
%
%The default value is \verb#false#.


\subsection[iprint]{\tt integer :: iprint}

This indicates the level of verbosity of the output from 0 (``low''),
the bare minimum, to 3 (``high''), which corresponds to full debugging output.

The default value is 1.

\subsection[optimisation]{\tt integer :: optimisation}

This indicates the level of optimisation used in the code. This is a
trade between speed and memory. A positive number indicates fastest execution time at the cost
of more memory. Zero or negative numbers indicates a smaller memory footprint - at increased
execution time.

At the moment the only values that have an effect are \verb#optimisation<=0# (low memory) and \verb#optimisation>0# (fast)

The default value is 3.


\subsection[length\_unit]{\tt character(len=20) :: length\_unit}
The length unit to be used for writing quantities in the output file
{\tt seedname.wout}.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}]  \verb#Ang# (default)
\item[{\bf --}]  \verb#Bohr#
\end{itemize}

\subsection[devel\_flag]{\tt character(len=50) :: devel\_flag}

Not a regular keyword. Its purpose is to allow a developer to pass a
string into the code to be used inside a new routine as it is developed.

No default.

%\subsection[calc\_only\_A]{\tt logical :: calc\_only\_A}
%\red{Not yet implemented}
%
%If $\verb#calc_only_A#=\verb#.true.#$, then the \textit{ab initio}
%code, eg \textsc{pwscf},
%calculates only $A_{mn}^{(\mathbf{k})}$. Otherwise, both
%$M_{mn}^{(\mathbf{k,b})}$ and $A_{mn}^{(\mathbf{k})}$ are
%calculated.
%
%The default value of this parameter is \verb#false#.


\subsection[exclude\_bands]{\tt integer :: exclude\_bands(:)}

A k-point independent list of states to excluded from the calculation
 of the overlap matrices;
 for example to select only valence states, or ignore semi-core states.
 This keyword is passed to the first-principles code via the
 {\tt seedname.nnkp} file. For example, to exclude bands 2, 6, 7, 8
 and 12:

 \verb#exclude_bands : 2, 6-8, 12#

\subsection[select\_projections]{\tt integer :: select\_projections(:)}

A list of projections to be included in the wannierisation procedure.
In the case that \verb#num_proj# is greater than \verb#num_wann#,
  this keyword allows a subset of the projections in the projection matrices to be used.
For example, to select the projections given by the indices 2, 6, 7, 8 and 12:

 \verb#select_projections : 2, 6-8, 12#

\subsection[auto\_projections]{\tt logical :: auto\_projections}

If {\tt .true.} and no projections block is defined, then \wannier\ writes an additional block in the {\tt .nnkp} file during the pre-processing step, to instruct the interface code to automatically generate the $A_{mn}^{(\mathbf{k})}$.

For additional information on the behavior and on the added block, see Sec.~\ref{sec:auto-projections-block}.

\textbf{Note:} the interface code (e.g. \texttt{pw2wannier90.x}) must have at least one implementation of a
method to automatically generate initial projections in order for this option to be usable.

The default value of this parameter is $\verb#false#$.

\subsection[restart]{\tt character(len=20) :: restart}

If \verb#restart# is present the code will attempt to restart the calculation
from the {\tt seedname.chk } file. The value of the parameter
determines the position of the restart

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}]  \verb#default#. Restart from the point at which the
  check file {\tt seedname.chk} was written
\item[{\bf --}]  \verb#wannierise#. Restart from the beginning of the
  wannierise routine
\item[{\bf --}]  \verb#plot#. Go directly to the plotting phase
\item[{\bf --}]  \verb#transport#. Go directly to the transport routines


\end{itemize}


\subsection[wvfn\_formated]{\tt character(len=20) :: wvfn\_formatted}

If \verb#wvfn_formatted#=\verb#true#, then the wavefunctions will be
read from disk as formatted (ie ASCII) files; otherwise they will be
read as unformatted files. Unformatted is generally preferable as the
files will take less disk space and I/O is significantly
faster. However such files will not be transferable between all
machine architectures and formatted files should be used if
transferability is required (i.e., for test cases).

The default value of this parameter is $\verb#false#$.


\subsection[spin]{\tt character(len=20) :: spin}
For bands from a spin polarised calculation {\tt spin} determines which set
of bands to read in, either \verb#up# or \verb#down#.

The default value of this parameter is \verb#up#.


\subsection[timing\_level]{\tt integer :: timing\_level}

Determines the amount of timing information regarding the calculation
that will be written to the output file. A value of 1 produces the
least information.

The default value is 1.

\subsection[translate\_home\_cell]{\tt logical :: translate\_home\_cell}

Determines whether to translate the final Wannier centres to the home
unit cell at the end of the calculation. Mainly useful for molecular
systems in which the molecule resides entirely within the home unit
cell and user wants to write an xyz file ({\tt write\_xyz=.true.}) for
the WF centres to compare with the structure.

The default value is \verb#false#.

\subsection[write\_xyz]{\tt logical :: write\_xyz}

Determines whether to write the atomic positions and
final Wannier centres to an xyz file,
\verb#seedname_centres.xyz#, for subsequent
visualisation.

The default value is \verb#false#.

\subsection[write\_vdw\_data]{\tt logical :: write\_vdw\_data}

Determines whether to write \verb#seedname.vdw# for
subsequent post-processing by the \verb#w90vdw# utility
(in the \verb#utility/w90vdw/# directory of the
distribution) for calculating van der Waals energies.
Brillouin zone sampling must be at the Gamma-point only.

The default value is \verb#false#.


\section{Disentanglement}
These keywords control the disentanglement routine of
Ref.~\cite{souza-prb01}, i.e., the iterative minimisation of $\omi$. This
routine will be activated if \verb#num_wann#$\:<\:$\verb#num_bands#.


\subsection[dis\_win\_min]{\tt real(kind=dp) :: dis\_win\_min}
The lower bound of the outer energy window for the disentanglement
procedure. Units are eV.

The default is the lowest eigenvalue in the system.

\subsection[dis\_win\_max]{\tt real(kind=dp) :: dis\_win\_max}
The upper bound of the outer energy window for the disentanglement
procedure. Units are eV.

The default is the highest eigenvalue in the given states (i.e., all states
are included in the disentanglement procedure).

\subsection[dis\_froz\_min]{\tt real(kind=dp) :: dis\_froz\_min}
The lower bound of the inner energy window for the disentanglement
procedure.  Units are eV.

If \verb#dis_froz_max# is given, then the default for
\verb#dis_froz_min# is \verb#dis_win_min#.


\subsection[dis\_froz\_max]{\tt real(kind=dp) :: dis\_froz\_max}
The upper bound of the inner (frozen) energy window for the
disentanglement procedure. If \verb#dis_froz_max# is not specified,
then there are no frozen states. Units are eV.

No default.

\subsection[dis\_num\_iter]{\tt integer :: dis\_num\_iter}
In the disentanglement procedure, the
number of iterations used to extract the most connected subspace.

The default value is 200.

\subsection[dis\_mix\_ratio]{\tt real(kind=dp) :: dis\_mix\_ratio}
In the disentanglement procedure, the mixing parameter to use for
convergence (see pages 4-5 of Ref.~\cite{souza-prb01}). A value of 0.5
is a `safe' choice. Using 1.0 (i.e., no mixing) often gives faster
convergence, but may cause the minimisation of $\omi$ to be unstable
in some cases.

Restriction: $0.0<\:${\tt dis\_mix\_ratio}$\:\leq 1.0$

The default value is 0.5

\subsection[dis\_conv\_tol]{\tt real(kind=dp) :: dis\_conv\_tol}

In the disentanglement procedure, the minimisation of $\omi$ is said
to be converged if the fractional change in the gauge-invariant spread
between successive iterations is less than
\verb#dis_conv_tol# for \verb#dis_conv_window# iterations. Units are \AA$^2$.

The default value is 1.0E-10


\subsection[dis\_conv\_window]{\tt integer :: dis\_conv\_window}

In the disentanglement procedure, the minimisation is said to be converged
if the fractional change in the spread between successive
iterations is less than
\verb#dis_conv_tol# for \verb#dis_conv_window# iterations.

The default value of this parameter is 3.

\subsection[dis\_spheres\_num]{\tt integer :: dis\_spheres\_num}
Number of spheres in reciprocal space where the k-dependent
disentanglement is performed. No disentanglement is performed for
those k-points that are not included in any of the spheres.

The default is 0, which means disentangle at every k-point in the full BZ (the standard mode in Wannier90).


\subsection[dis\_spheres\_first\_wann]{\tt integer :: dis\_spheres\_first\_wann}
Index of the first band that has to be considered as a Wannier function. Used only if {\tt dis\_spheres\_num} is greater than zero.
At k-points where disentanglement is not performed the bands from
{\tt dis\_spheres\_first\_wann} to {\tt dis\_spheres\_first\_wann+num\_wann} are used
to wannierise. The bands excluded using {\tt exclude\_bands} should not
be counted.

The default is 1, the band at the lowest energy.


\subsection[dis\_spheres]{dis\_spheres}
Each line gives the coordinate $\mathbf{K}=K_1 \mathbf{B}_{1} + K_2
\mathbf{B}_{2} + K_3 \mathbf{B}_3$ of a k-point representing the
center of one of the spheres used for k-dependent disentanglement.
The same crystallographic units as for {\tt kpoints} are used here.
Each k-point coordinate $\mathbf{K}^i$ must the followed by the
respectice sphere radius $r_{i}$ in inverse angstrom (on the same line).

The number of lines must be equal to {\tt dis\_spheres\_num}.

\noindent  \verb#begin dis_spheres#
$$
\begin{array}{cccc}
 K^{1}_{1} & K^{1}_{2} & K^{1}_{3} & r_{1} \\
 K^{2}_{1} & K^{2}_{2} & K^{2}_{3} & r_{2} \\
\vdots
\end{array}
$$
\verb#end dis_spheres#

There is no default.


\section{Wannierise}\label{sec:wann_params}
Iterative minimisation of $\omt$, the non-gauge-invariant part of the
spread functional.

\subsection[num\_iter]{\tt integer :: num\_iter}

Total number of iterations in the minimisation procedure.
Set {\tt num\_iter=0} if you wish to generate
  projected WFs rather than maximally-localized WFs (see Example~8 in
  the Tutorial).

The default value is 100

\subsection[num\_cg\_steps]{\tt integer :: num\_cg\_steps}

Number of conjugate gradient steps to take before resetting to steepest descents.

The default value is 5

\subsection[conv\_window]{\tt integer :: conv\_window}

If {\tt conv\_window}$\:>1$, then the minimisation is said to be
  converged if the change in $\Omega$ over {\tt
  conv\_window} successive iterations is less than {\tt
  conv\_tol}. Otherwise, the minimisation proceeds for
  {num\_iter} iterations (default).

The default value is -1

\subsection[conv\_tol]{\tt real(kind=dp) :: conv\_tol}

If {\tt conv\_window}$\:>1$, then this is the convergence tolerance on
$\Omega$, otherwise not used. Units are \AA$^2$.

The default value is 1.0E-10

\subsection[precond]{\tt logical :: precond}

Whether or not to use preconditioning to speed up the minimization of
the spreads. This is based on the same idea as the classical
Tetter-Payne-Allan preconditionning for DFT and dampens the
high-frequency oscillations of the gradient due to contributions from
large real lattice vectors. It is useful when the optimization is
slow, especially on fine grids. When \verb#optimisation<3#, this uses
a slower algorithm to save memory.

The default value is \verb#false#.

\subsection[conv\_noise\_amp]{\tt real(kind=dp) :: conv\_noise\_amp}

If {\tt conv\_noise\_amp}$\:>0$, once convergence (as defined above) is
achieved, some random noise $f$ is added to the search direction, and the
minimisation is continued until convergence is achieved once more. If
the same value of $\Omega$ as before is arrived at, then the calculation
is considered to be converged. If not, then random noise is added
again and the procedure repeated up to a maximum of {\tt
  conv\_noise\_num} times. {\tt conv\_noise\_amp} is the amplitude of
the random noise $f$ that is added to the search direction:
$0 < |f| <\:${\tt conv\_noise\_amp}. This functionality requires {\tt
  conv\_window}$\:>1$. If {\tt conv\_window} is not specified, it is set
to the value 5 by default.

If {\tt conv\_noise\_amp}$\:\leq 0$, then no noise is added (default).

The default value is -1.0

\subsection[conv\_noise\_num]{\tt integer :: conv\_noise\_num}

If {\tt conv\_noise\_amp}$\:>0$, then this is the number of times in the
minimisation that random noise is added.

The default value is 3

\subsection[num\_dump\_cycles]{\tt integer :: num\_dump\_cycles}
Write sufficient information to do a restart every
\verb#num_dump_cycles# iterations.

The default is 100

\subsection[num\_print\_cycles]{\tt integer :: num\_print\_cycles}
Write data to the master output file {\tt seedname.wout} every
\verb#num_print_cycles# iterations.

The default is 1

\subsection[write\_r2mn]{\tt logical :: write\_r2mn}

If $\verb#write_r2mn#=\verb#true#$, then the matrix elements
$\langle m|r^2|n\rangle$ (where $m$ and $n$ refer to WF) are written
to file \verb#seedname.r2mn# at the end of the Wannierisation
procedure.

The default value of this parameter is \verb#false#.


\subsection[guiding\_centres]{\tt logical :: guiding\_centres}
Use guiding centres during the minimisation, in order to avoid
local minima.

\wannier\ uses a logarithm definition of the spread functional. As we are taking the log of a complex argument there is a possibility that the algorithm might make inconsistent choices for the branch cut. This manifests itself as complex WF with a large spread. By using guiding centres the code will attempt to make a consistent choice of branch cut. Experience shows that with \verb#guiding_centres# set to true this problem is avoided and doing so
does not cause any problems. For this reason we recommend setting \verb#guiding_centres# to true where possible (it is only not possible if an explicit projection block is not defined).

The default value is \verb#false#.

\subsection[num\_guide\_cycles]{\tt integer :: num\_guide\_cycles}
If \verb#guiding_centres# is set to true, then the
guiding centres are used only every \verb#num_guide_cycles#.

The default value is 1.

\subsection[num\_no\_guide\_iter]{\tt integer :: num\_no\_guide\_iter}
If \verb#guiding_centres# is set to true, then the
guiding centres are used only after \verb#num_no_guide_iter#
minimisation iterations have been completed.

The default value is 0.

\subsection[trial\_step]{\tt real(kind=dp) :: trial\_step}
The value of the trial step for the parabolic fit in the line
search minimisation used in the minimisation of the spread
function. Cannot be used in conjunction with \verb#fixed_step# (see
below). If the minimisation procedure doesn't converge, try decreasing
the value of \verb#trial_step# to give a more accurate line search.

The default value is 2.0

\subsection[fixed\_step]{\tt real(kind=dp) :: fixed\_step}
If this is given a value in the input file, then a fixed step of length
\verb#fixed_step# (instead of a parabolic
line search) is used at each iteration of the spread function
minimisation. Cannot be used in conjunction with
\verb#trial_step#. This can be useful in cases in which minimisation
with a line search fails to converge.

There is no default value.

\subsection[use\_bloch\_phases]{\tt logical :: use\_bloch\_phases}

Determines whether to use the Bloch functions as the
initial guess for the projections. Can only be used if
\verb#disentanglement = false#.

The default value is \verb#false#.


\subsection[site\_symmetry]{\tt logical :: site\_symmetry}

Construct symmetry-adapted Wannier functions.
For the detail of the theoretical background, see Ref.~\cite{sakuma-prb13}.
Cannot be used in conjunction with the inner (frozen) energy window.

The default value is \verb#false#.

\subsection[symmetrize\_eps]{\tt real(kind=dp) :: symmetrize\_eps}

Convergence threshold to check whether the symmetry condition (Eq. (19) in Ref.~\cite{sakuma-prb13})
on the unitary matrix $\Uk$ is satisfied or not.
See also Eq. (29) in Ref.~\cite{sakuma-prb13}.
Used when \verb#site_symmetry = .true#.

The default value is 1.0E-3.

% VV: Removed from Wannier90 and moved to pw2wannier90.f90
%\subsection[scdm\_proj]{\tt logical :: scdm\_proj}
%If {\tt scdm\_proj=true} then the $A_{mn}^{(\mathbf{k})}$ matrices are generated with the SCDM-k method of Ref.~\cite{LinLin-ArXiv2017}. In this case, one also needs to specify the {\tt scdm\_entanglement} keyword. One then needs to run {\tt wannier90.x -pp seedname} to generate the {\tt seedname.nnkp} file, to be used by a first-principle code (at the moment only interface available is with the QuantumEspresso code).
%
%The default value is {\tt false}.
%
%\subsection[scdm\_entanglement]{\tt integer :: scdm\_entanglement}
%Select the functional form for the occupation number matrix $f(\epsilon_{n\mathbf{k}})$ for the SCDM-k method.
%Only three integer values are allowed:
%
%\noindent {\tt isolated}: $f(\epsilon_{n\mathbf{k}})$ is the identity matrix $I_{n\mathbf{k}}$
%
%\noindent {\tt erfc}: The occupation number matrix is given by: $$f(\epsilon_{n\mathbf{k}})=\frac{1}{2}\mathtt{ERFC}\left(\frac{\epsilon_{n\mathbf{k}} - \mu}{\sigma}\right) $$
%
%\noindent {\tt gaussian}: The occupation number matrix is given by $$f(\epsilon_{n\mathbf{k}})=\mathtt{EXP}\left(-\frac{(\epsilon_{n\mathbf{k}}-\mu)^2}{\sigma^2}\right)$$
%
%The default value is {\tt isolated}.
%
%\subsection[scdm\_mu]{\tt real(kind=dp) :: scdm\_mu}
%The value of the $\mu$ parameter in the formulas above. It is strictly required only when {\tt scdm\_entanglement=erfc} or {\tt gaussian}. It defines the characteristic energy for the occupation numbers matrix, in units of eV. If {\tt scdm\_entanglement=erfc}, it gives the mean value of the complementary error function. If {\tt scdm\_entanglement=gaussian}, it gives the mean value of the gaussian instead.
%
%The default value is {\tt 0 eV}.
%
%\subsection[scdm\_sigma]{\tt real(kind=dp) :: scdm\_sigma}
%The value of the $\sigma$ parameter in the formulas for the occupation numbers matrix. It is strictly required only when {\tt scdm\_entanglement=erfc} or {\tt gaussian}. It defines the spread of the occupation numbers matrix around $\mu$, and as such it must be a positive real number. It must be given in units of eV.
%
%The default value is {\tt 1.0 eV}.

\subsection[slwf\_num]{\tt integer :: slwf\_num}
The number of objective Wannier functions for selective localisation in the selectively localised Wannier function (SLWF) method of Ref.~\cite{Marianetti}. These functions are obtained by minimising the spread functional only with respect to the degrees of freedom of a subset of {\tt slwf\_num} $<$ {\tt num\_wann} functions. At convergence, the objective WFs will have a minimum cumulative spread, whereas the remaining {\tt num\_wann} $-$ {\tt slwf\_num} functions are left unoptimised. The initial guesses for the objective WFs are given by the first {\tt slwf\_num} orbitals in the {\tt projections} block. If {\tt slwf\_num = num\_wann} no selective minimisation is performed. In this case, \wannier\ will simply generate a set of {\tt num\_wann} MLWFs.

The default is {\tt num\_wann}.

\subsection[slwf\_constrain]{\tt logical :: slwf\_constrain}
If {\tt slwf\_constrain=true}, then the centres of the objective Wannier functions are constrained to either the centres of the first {\tt slwf\_num} orbitals in the {\tt projections} block or to new positions specified in the {\tt slwf\_centres} block (see Sec.~\ref{sec:centre_constraints}). In this case, a modified spread functional, $\Omega_c$, with the addition of a constraint term, as described in Ref.~\cite{Marianetti}.

The default is {\tt false}

\subsection[slwf\_lambda]{\tt real(kind=dp) :: slwf\_lambda}
The value of the Lagrange multiplier $\lambda$ for the constraint term in term added to modify the spread functional: $ \lambda \sum_{n=1}^{J'} \left(\overline{\mathbf{r}}_n - \mathbf{r}_{0n}\right)^2$, where $J'$ is {\tt slwf\_num}, and $\overline{\mathbf{r}}_{n}$ and $\mathbf{r}_{0n}$ are the centre and target centre, respectively, for the $n^{\text{th}}$ objective WF.

The default is {\tt 0.0}.

\subsection{Constraints on centres}
\label{sec:centre_constraints}

If {\tt slwf\_constrain=true}, then by default the centres to which the {\tt slwf\_num} objective Wannier function centres are constrained are given by the first {\tt slwf\_num} rows of the {\tt projections} block.

Optionally, the {\tt slwf\_centres} block may be used to define alternative target centres for some or all of the {\tt slwf\_num} objective Wannier functions.

The block below shows an example of how to set the constraints:

\noindent \verb#begin slwf_centres# \\
\verb#   2  0.0   0.0  0.0# \\
\verb#   4  0.25  0.0  0.0# \\
\verb#end slwf_centres#

\begin{itemize}
\item The first line sets the constraint for the centre of objective WF number 2 (as defined by the order of WFs in the {\tt projections} block) to (0.0,0.0,0.0) in fractional co-ordinates.
\item The second line sets the constraint for the centre of objective WF number 4 (as defined by the order of WFs in the {\tt projections} block) to (0.25,0.0,0.0) in fractional co-ordinates.
\item The target centres of all other objective Wannier functions remain as the centres given in the corresponding rows of the {\tt projections} block.
\end{itemize}

\section{Post-Processing}
\label{sec:post-p}

 Capabilities:

\begin{itemize}
\item[{\bf --}]  Plot the WF
\item[{\bf --}]  Plot the interpolated band structure
\item[{\bf --}]  Plot the Fermi surface
\item[{\bf --}]  Output the Hamiltonian in the WF basis
\item[{\bf --}]  Transport calculation (quantum conductance and
  density of states)
%\item[{\bf --}]  Plot the density of states.
\end{itemize}


\subsection[wannier\_plot]{\tt logical :: wannier\_plot}

If $\verb#wannier_plot#=\verb#true#$, then the code will write out the
Wannier functions in a format specified by \verb#wannier_plot_format#

The default value of this parameter is \verb#false#.


\subsection[wannier\_plot\_list]{\tt integer :: wannier\_plot\_list(:)}

 A list of WF to plot. The WF numbered
 as per the {\tt seedname.wout} file after the minimisation of the
 spread.

 The default behaviour is to plot all WF. For example,
 to plot WF 4, 5, 6 and 10:

 \verb#wannier_plot_list : 4-6, 10#


\subsection[wannier\_plot\_supercell]{\tt integer :: wannier\_plot\_supercell}

The code generates the WFs on a grid corresponding to a `super-unit-cell'.
If \verb#wannier_plot_supercell# is provided as a single integer,
then the size of the super-unit-cell is \verb#wannier_plot_supercell# times
the size of the unit cell along all three linear dimensions (the `home' unit cell
is kept approximately in the middle); otherwise, if three integers are
provided, the size of the super-unit-cell is \verb#wannier_plot_supercell(i)#
times the size of the unit cell along the $i-$th linear dimension.

The default value is 2.


\subsection[wannier\_plot\_format]{\tt character(len=20) :: wannier\_plot\_format}

WF can be plotted in either XCrySDen (xsf) format or Gaussian cube
format. The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#xcrysden# (default)
\item[{\bf --}] \verb#cube#
%\item[{\bf --}] gopenmol
%\item[{\bf --}] dan
\end{itemize}

If {\tt wannier\_plot\_format=xsf}: the code outputs the WF on the entire super-unit-cell
specified by {\tt wannier\_plot\_supercell}.

If {\tt wannier\_plot\_format=cube}: the code outputs the WF on a grid that is smaller
than the super-unit-cell specified by {\tt wannier\_plot\_supercell}. This grid is
determined by {\tt wannier\_plot\_mode}, {\tt wannier\_plot\_radius} and {\tt wannier\_plot\_scale},
described in detail below.

The code is able to output Gaussian cube files for systems with non-orthogonal lattice vectors.
Many visualisation programs (including XCrySDen), however, are only able to handle cube files for systems
with \emph{orthogonal} lattice vectors. One visualisation program that is capable of dealing with non-orthogonal lattice vectors is
VESTA (\url{http://jp-minerals.org/vesta/en/}).\footnote{It's worth noting that another
  visualisation program, VMD (\url{http://www.ks.uiuc.edu/Research/vmd}), is able to
  deal with certain special cases of non-orthogonal lattice
  vectors; see \url{http://www.ks.uiuc.edu/Research/vmd/plugins/molfile/cubeplugin.html} for details.}

\subsection[wannier\_plot\_mode]{\tt character(len=20) :: wannier\_plot\_mode}

Choose the mode in which to plot the WF, either as a molecule
or as a crystal.
%Only relevant if {\tt wannier\_plot\_format=xcrysden}.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#crystal# (default)
\item[{\bf --}] \verb#molecule#
\end{itemize}

If {\tt wannier\_plot\_format=cube}:
\begin{itemize}
\item if {\tt wannier\_plot\_mode = molecule}, then wherever the WF centre sits in the supercell, the origin of the cube is shifted (for the purpose of plotting only, ie, nothing is done to the U matrices etc) to coincide with the centre of mass of the atomic positions specified by the user in the {\tt *.win} input file. These atomic positions are also written to the cube file, so when it is visualised, the WF appears superimposed on the molecular structure.
\item if {\tt wannier\_plot\_mode = crystal}, then the WF is not shifted, but instead the code searches for atoms that are within a radius of {\tt wannier\_plot\_scale} $\times$ {\tt wannier\_plot\_radius} of the WF centre and writes the coordinates of these atoms to the cube file. In this way, when the cube file is visualised, the WF appears superimposed on the nearest atoms to the WF centre.
\item {\tt crystal} mode can be used for molecules, and {\tt molecule} mode can be used for crystals.
\end{itemize}

\subsection[wannier\_plot\_radius]{\tt real(kind=dp) ::
  wannier\_plot\_radius}

If {\tt wannier\_plot\_format=cube}, then {\tt
  wannier\_plot\_radius} is the radius of the sphere that must fit inside the parallelepiped in which the WF is plotted. {\tt wannier\_plot\_radius} must be greater than
  0. Units are \AA.

The default value is 3.5.

\subsection[wannier\_plot\_scale]{\tt real(kind=dp) ::
  wannier\_plot\_scale}
If {\tt wannier\_plot\_format=cube} and {\tt wannier\_plot\_mode=crystal}, then the code searches for atoms that are within a radius
of {\tt wannier\_plot\_scale} $\times$ {\tt wannier\_plot\_radius} of the WF centre and writes the coordinates of these atoms to the cube file.
In this way, when the cube file is visualised, the WF appears superimposed on the nearest atoms to the WF centre. {\tt wannier\_plot\_scale} must
be greater than 0. This parameter is dimensionless.

The default value is 1.0.

\subsection[wannier\_plot\_spinor\_mode]{\tt character(len=20) :: wannier\_plot\_spinor\_mode}
If $\verb#spinors#=\verb#true#$ then this parameter controls the
quantity to plot. For a spinor WF with components $[\phi,\psi]$ the quatity plotted is
\begin{itemize}
\item[{\bf --}] \verb#total# (default). $\sqrt{[|\phi|^2+|\psi|^2}$
\item[{\bf --}] \verb#up#. $|\phi|\times sign(Re\{\phi\})$ if $\verb#wannier_plot_spinor_mode#=\verb#true#$,
 otherwise $|\phi|$
\item[{\bf --}] \verb#down#. $|\psi|\times sign(Re\{\psi\})$ if
  $\verb#wannier_plot_spinor_mode#=\verb#true#$, otherwise $|\psi|$
\end{itemize}
Note: making a visual representation of a spinor WF is not as
straightforward as for a scalar WF. While  a scalar WF is typically a
real valued function, a spinor WF is a complex, two component
spinor. \wannier\ is able to plot several different quantities derived
from a spinor WF which should give you a good idea of the nature of
the WF.

\subsection[wannier\_plot\_spinor\_phase]{\tt logical ::   wannier\_plot\_spinor\_phase}
If $\verb#wannier_plot_spinor_phase#=\verb#true#$ phase information will
be taken into account when plotting a spinor WF.

\subsection[bands\_plot]{\tt logical :: bands\_plot}

If $\verb#bands_plot#=\verb#true#$, then the code will calculate the band
structure, through Wannier interpolation,
 along
the path in k-space defined by \verb#bands_kpath# using \verb#bands_num_points# along the first
section of the path and write out an output file in a format specified
by \verb#bands_plot_format#.

The default value is \verb#false#.


\subsection[kpoint\_path]{kpoint\_path}
Defines the path in k-space along which to calculate the
bandstructure. Each line gives the start and end point (with labels)
for a section of the path. Values are in fractional coordinates with
respect to the primitive reciprocal lattice vectors.

\noindent  \verb#begin kpoint_path#
$$
\begin{array}{cccccccc}
G & 0.0 & 0.0 & 0.0 & L & 0.0 & 0.0 & 1.0 \\
L & 0.0 & 0.0 & 1.0 & N & 0.0 & 1.0 & 1.0 \\
\vdots
\end{array}
$$
\verb#end kpoint_path#


There is no default

\subsection[bands\_num\_points]{\tt integer :: bands\_num\_points}

If $\verb#bands_plot#=\verb#true#$, then the number of points along
the first section of the bandstructure plot given by
\verb#kpoint_path#. Other sections will have the same density of
k-points.

The default value for \verb#bands_num_points# is 100.


\subsection[bands\_plot\_format]{\tt character(len=20) :: bands\_plot\_format}

Format in which to plot the interpolated band structure.
The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#gnuplot# (default)
\item[{\bf --}] \verb#xmgrace#
\end{itemize}
Note: it is possible to request output in both formats eg
$\verb#bands_format#=\verb#gnuplot xmgrace#$


\subsection[bands\_plot\_project]{\tt integer :: bands\_plot\_project(:)}

If present \wannier\ will compute the contribution of this set of WF to the
states at each point of the interpolated band structure.
The WF are numbered according to the seedname.wout file. The result is written
in the {\tt seedname\_band.dat} file, and a corresponding gnuplot script to
{\tt seedname\_band\_proj.dat} .

 For example, to project on to WFs 2, 6, 7, 8 and 12:

 \verb#bands_plot_project : 2, 6-8, 12#


\subsection[bands\_plot\_mode]{\tt character(len=20) :: bands\_plot\_mode}

To interpolate the band structure along the k-point path,
either use the Slater-Koster interpolation scheme
or truncate the Hamiltonian matrix in the WF basis.
Truncation criteria are provided by \verb#hr_cutoff#
and \verb#dist_cutoff#.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#s-k# (default)
\item[{\bf --}] \verb#cut#
\end{itemize}

\subsection[bands\_plot\_dim]{\tt integer :: bands\_plot\_dim}

Dimension of the system.
If $\verb#bands_plot_dim#<\:$3 and $\verb#bands_plot_mode#=\verb#cut#$,
lattice vector $\mathbf{R}=N_1 \mathbf{A}_{1} + N_2 \mathbf{A}_{2} + N_3 \mathbf{A}_3$,
where $N_i=0$ if $\mathbf{A}_i$ is parallel to any of the
confined directions specified by \verb#one_dim_axis#,
are exclusively used in the band structure interpolation.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] 3 (default)
\item[{\bf --}] 2
\item[{\bf --}] 1
\end{itemize}


\subsection[fermi\_surface\_plot]{\tt logical :: fermi\_surface\_plot}

If $\verb#fermi_surface_plot#=\verb#true#$, then the code will calculate,
through Wannier interpolation, the
eigenvalues on a regular grid with \verb#fermi_surface_num_points# in
each direction. The code will write a file in bxsf format which can be
read by XCrySDen in order to plot the Fermi surface.

The default value is \verb#false#.


\subsection[fermi\_surface\_num\_points]{\tt integer :: fermi\_surface\_num\_points}

If $\verb#fermi_surface_plot#=\verb#true#$, then the number of divisions in
the regular k-point grid used to calculate the Fermi surface.

The default value for \verb#fermi_surface_num_points# is 50.


\subsection[fermi\_energy]{\tt real(kind=dp) :: fermi\_energy}
The Fermi energy in eV. This parameter is written into the bxsf file.
If {\tt fermi\_energy} is specified, {\tt
    fermi\_energy\_min}, {\tt fermi\_energy\_max}, and {\tt
    fermi\_energy\_step} should not be specified, and vice-versa.

%Whilst this is not directly used by the
%\wannier, it is a useful parameter to set as it will be written
%into the bxsf file.

% There is no default value.
The default value is 0.0


\subsection[fermi\_energy]{\tt real(kind=dp) :: fermi\_energy\_min}
Instead of specifyfing a single Fermi energy, it is possible to scan
the Fermi level over a range of values, and recompute certain
quantities for each $\varepsilon_F$.\footnote{Scanning the Fermi level
  is currently supported only by the {\tt postw90} module {\tt berry},
  for {\tt berry\_task=ahc,morb}. For all other functionalities that
  require a knowledge of $\varepsilon_F$, use {\tt fermi\_energy}
  instead.}  This is the minimum value in the range (in eV).

There is no default value.

\subsection[fermi\_energy]{\tt real(kind=dp) :: fermi\_energy\_max}
The maximum value in the range of Fermi energies. Units are eV.

The default value is {\tt fermi\_energy\_min}+1.0.

\subsection[fermi\_energy]{\tt real(kind=dp) :: fermi\_energy\_step}
Difference between consecutive values of the Fermi energy when
scanning from {\tt fermi\_energy\_min} to {\tt
  fermi\_energy\_max}. Units are eV.

The default value is 0.01.


\subsection[fermi\_surface\_plot\_format]{\tt character(len=20) ::
  fermi\_surface\_plot\_format}

Format in which to plot the Fermi surface.
The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#xcrysden#  (default)
\end{itemize}

\subsection[write\_hr]{\tt logical :: write\_hr}

If $\verb#write_hr#=\verb#true#$, then the Hamiltonian matrix in the
WF basis will be written to a file {\tt seedname\_hr.dat}.

The default value is {\tt false}.

\subsection[write\_rmn]{\tt logical :: write\_rmn}

If $\verb#write_rmn#=\verb#true#$, then the position operator in the
WF basis will be written to a file {\tt seedname\_r.dat}.

The default value is {\tt false}.

\subsection[write\_bvec]{\tt logical :: write\_bvec}

If $\verb#write_bvec#=\verb#true#$, then the the matrix elements of
bvector and their weights will be written to a file {\tt seedname.bvec}.

The default value is {\tt false}.


\subsection[write\_tb]{\tt logical :: write\_tb}

If $\verb#write_tb#=\verb#true#$, then the lattice vectors, together
with the Hamiltonian and position-operator matrices in the WF basis,
will be written to a file {\tt seedname\_tb.dat}, in units
of Angstrom and eV.

The default value is {\tt false}.


\subsection[transport]{\tt logical :: transport}

If $\verb#transport#=\verb#true#$, then the code will calculate
quantum conductance and density of states of a one-dimensional system.
The results will be written to files \verb#seedname_qc.dat#
and \verb#seedname_dos.dat#, respectively.
Since both quantities are a function of energy,
they will be evaluated from \verb#tran_win_min# to \verb#tran_win_max#
with an interval of \verb#tran_energy_step#.

The default value of this parameter is \verb#false#.

\subsection[transport\_mode]{\tt character(len=20) :: transport\_mode}

If $\verb#transport_mode#=\verb#bulk#$, quantum conductance
and density of states are calculated for a perfectly-periodic one-dimensional system.
In this case, the transport part can either use
the Hamiltonian matrix in the WF basis generated by \wannier\
or a Hamiltonian matrix provided by the external file
{\tt seedname\_htB.dat}.

If $\verb#transport_mode#=\verb#lcr#$, quantum conductance and density
of states are calculated for a system where semi-infinite, left and
right leads are connected through a central conductor region.  In this
case, the transport part will work independently from the
disentanglement and wannierise procedure.  Details of the method is
described in Ref. \cite{nardelli-prb99}.

If $\verb#tran_read_ht# = \verb#true#$ then the
Hamiltonian matrices must be provided by
the five external files:
{\tt seedname\_htL.dat, seedname\_htLC.dat, seedname\_htC.dat,
seedname\_htCR.dat, seedname\_htR.dat}.
If $\verb#tran_read_ht# = \verb#false#$ then the Hamiltonian
matrices are found automatically provided the supercell adheres to
conditions outlined in Section~\ref{sec:2c2}.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#bulk#  (default)
\item[{\bf --}] \verb#lcr#
\end{itemize}

\subsection[tran\_win\_min]{\tt real(kind=dp) :: tran\_win\_min}
The lower bound of the energy window for the transport calculation.
Units are eV.

The default value is -3.0.

\subsection[tran\_win\_max]{\tt real(kind=dp) :: tran\_win\_max}
The upper bound of the energy window for the transport calculation.
Units are eV.

The default value is 3.0.

\subsection[tran\_energy\_step]{\tt real(kind=dp) :: tran\_energy\_step}
Sampling interval of the energy values from \verb#tran_win_min#
to \verb#tran_win_max#.
Units are eV.

The default value is 0.01.

\subsection[fermi\_energy]{\tt real(kind=dp) :: fermi\_energy}
The Fermi energy in eV. The energy axis of the quantum conductance and
density of states data will be shifted rigidly by this amount.

The default value is 0.0

\subsection[tran\_num\_bb]{\tt integer :: tran\_num\_bb}
Size of a bulk Hamiltonian matrix.
This number is equal to the number of WFs in one principal
layer.

A one-dimensional system can be viewed
as an array of principal layers
which are defined in a way that
localized basis functions inside a certain principal layer
only interact with those in the nearest neighbor principal layer.
In \wannier\ a principal layer will be an integer multiple
of a unit cell, and the size is determined by
\verb#hr_cutoff# and/or \verb#dist_cutoff#.
The criterion is rather arbitrary
when WFs are adopted as a localized basis set,
and it is up to a user's choice.

The default value is 0.

\subsection[tran\_num\_ll]{\tt integer :: tran\_num\_ll}
Size of a left-lead Hamiltonian matrix.
If $\verb#transport_mode# = \verb#lcr#$ and
$\verb#tran_read_ht# = \verb#false#$ then
\verb#tran_num_ll# is the number of Wannier functions
in a principal layer.

The default value is 0.

\subsection[tran\_num\_rr]{\tt integer :: tran\_num\_rr}
Size of a right-lead Hamiltonian matrix.

The default value is 0.

\subsection[tran\_num\_cc]{\tt integer :: tran\_num\_cc}
Size of a conductor Hamiltonian matrix.

The default value is 0.

\subsection[tran\_num\_lc]{\tt integer :: tran\_num\_lc}
Number of columns in a left-lead\_conductor Hamiltonian matrix.
Number of rows must be equal to \verb#tran_num_ll#.


The default value is 0.

\subsection[tran\_num\_cr]{\tt integer :: tran\_num\_cr}
Number of rows in a conductor\_right-lead Hamiltonian matrix.
Number of columns must be equal to \verb#tran_num_rr#.

The default value is 0.

\subsection[tran\_num\_cell\_ll]{\tt integer :: tran\_num\_cell\_ll}
Number of unit cells in one principal layer of left lead.
Used if $\verb#transport_mode# = \verb#lcr#$ and
$\verb#tran_read_ht# = \verb#false#$.

The default value is 0.

\subsection[tran\_num\_cell\_rr]{\tt integer :: tran\_num\_cell\_rr}
Number of unit cells in one principal layer of right lead.
Not used at present.

The default value is 0.

\subsection[tran\_num\_bandc]{\tt integer :: tran\_num\_bandc}

Half-bandwidth+1 of a band-diagonal conductor Hamiltonian matrix.

The Hamiltonian matrix of a central conductor part, which is
read from \verb#seedname_htC.dat#, will be diagonally dominant
when \verb#tran_num_cc# is very large.
\verb#tran_num_bandc# is used to construct
a compact matrix which contains
the non-zero band-diagonal part of a full conductor Hamiltonian matrix.
Setting this parameter is only meaningful when
\verb#tran_num_bandc# is greater than
\verb#tran_num_lc# and \verb#tran_num_cr#.

The default value is 0.

\subsection[tran\_write\_ht]{\tt logical :: tran\_write\_ht}

If $\verb#tran_write_ht#=\verb#true#$, then the Hamiltonian matrix
formatted for the transport calculation will be written
to a file \verb#seedname_htB.dat#.

The default value is {\tt false}.

\subsection[tran\_read\_ht]{\tt logical :: tran\_read\_ht}

If $\verb#tran_write_ht#=\verb#true#$, then the Hamiltonian matrix
formatted for the transport calculation will be read
from a set of files described in the
parameter \verb#transport_mode#.
Set $\verb#tran_write_ht#=\verb#false#$ to perform automated
lcr calculations (see Section~\ref{sec:2c2}).

The default value is {\tt false}.

\subsection[tran\_use\_same\_lead]{\tt logical :: tran\_use\_same\_lead}

If $\verb#tran_use_same_lead#=\verb#true#$, then the
left and the right leads are the same. In this case,
\verb#seedname_htR.dat# is not required.

The default value is {\tt true}.

\subsection[tran\_group\_threshold]{\tt real(kind=dp) :: tran\_group\_threshold}

Used to group and sort Wannier functions according to the positions of their centres.
Wannier functions in a group are within \verb#tran_group_threshold#
from one another in \verb#x,y# and \verb#z# directions. Units are \AA

The default is 0.15

\subsection[translation\_centre\_frac]{\tt real(kind=dp) :: translation\_centre\_frac(3)}

Centre of the unit cell to which the final Wannier centres are
translated. Numbers are in fractional coordinates with respect to the
lattice vectors.

The default value is (0.0,0.0,0.0).

\subsection[use\_ws\_distance]{\tt logical :: use\_ws\_distance}

Improves the interpolation of the k-space Hamiltonian, by
applying a translation to each WF by a basis
vector of the super-lattice that minimises the distance between their centres.
The translation is dependent on both WF and on the unit cell vector
to which they belong, i.e., translate function $W_j({\bf r}-{\bf R})$ inside
the Wigner-Seitz cell centred on WF $W_i({\bf r})$.

For a longer explanation, see Chapter~\ref{chap:interpolation}.

If {\tt false} the code puts all the WF in the home cell, only possible choice until wannier90 v2.0.1.

The default value is {\tt true} (default changed since v.3.0). Introduced in v2.1.

\subsection[ws\_distance\_tol]{\tt real(kind=dp) :: ws\_distance\_tol}

Tolerance when determining whether two values $\|\mathbf{d}_{ij\mathbf{R}} + \tilde{\mathbf{R}}_{nml} \|$ and $\|\mathbf{d}_{ij\mathbf{R}} + \tilde{\mathbf{R}}_{n'm'l'} \|$ (as defined in chapter~\ref{chap:interpolation}) for the shortest distance between two Wannier functions are equivalent. If the difference in distance (in Angstrom) is less than \texttt{ws\_distance\_tol}, they are taken to be equivalent.

The default value is $10^{-5}$.

\subsection[ws\_search\_size]{\tt :: ws\_search\_size}
Maximum absolute value for the integers $n,m,l$ that identify the super-lattice vectors $\tilde{\mathbf{R}}_{nml}$ (see chapter~\ref{chap:interpolation})
when searching for points inside the Wigner-Seitz cell.
If \verb#ws_search_size# is provided as a single integer,
then the number of repetitions of the Born-von Karman cell is the same
along all three linear dimensions; otherwise, if three integers are
provided, the number of repetitions along the $i-$th linear dimension is \verb#ws_search_size(i)#.
The variable is used both in \verb#hamiltonian.F90# and in \verb#ws_distance.F90#. In the latter case, its value is incremented by one in order to account for WFs whose centre wanders away from the original reference unit cell.\\
The default value is generally sufficient, but might need to be increased in case of elongated cells.

The default value is 2.


\subsection[write\_u\_matrices]{\tt logical :: write\_u\_matrices}

Write the $\mathbf{U}^{(\mathbf{k})}$ and $\mathbf{U}^{\mathrm{dis}(\mathbf{k})}$ matrices obtained at the end of wannierization to files
{\tt seedname\_u.mat} and {\tt seedname\_u\_dis.mat}, respectively.

The default value is {\tt false}.


\subsection[hr\_cutoff]{\tt real(kind=dp) :: hr\_cutoff}

The absolute value of the smallest matrix element of the
Hamiltonian in the WF basis.
If $h_{mn}(\mathbf{R})>\:${\tt
  hr\_cutoff}, then the matrix element
$h_{mn}(\mathbf{R})$ is retained and used in
the band structure interpolation (when $\verb#bands_plot_mode#=\verb#cut#$)
or in the transport calculation.
Otherwise it is deemed to be insignificant
and is discarded. Units are eV.

%The absolute value of the largest matrix element of the
%Hamiltonian in the WF basis at lattice vector $\mathbf{R}$ is given by
%$h_{\mathrm{max}}(\mathbf{R}) = \left|\mathrm{max}\:\:
%H_{mn}(\mathbf{R})\right|$. If $h_{\mathrm{max}}(\mathbf{R})>\:${\tt
%  hr\_cutoff}, then the matrix elements
%$H_{mn}(\mathbf{R})$ are retained in the Hamiltonian that is written
%to {\tt seedname.h.dat}. Otherwise they are deemed to be insignificant
%and are discarded.

The default value is 0.0.

\subsection[dist\_cutoff]{\tt real(kind=dp) :: dist\_cutoff}

The largest distance between two WFs for which
the Hamiltonian matrix element is retained and used in
the band interpolation (when $\verb#bands_plot_mode#=\verb#cut#$)
or in the transport calculation. Units are \AA.

The default value is 1000.0.

\subsection[dist\_cutoff\_mode]{\tt character(len=20) :: dist\_cutoff\_mode}

Dimension in which the distance between two WFs is calculated.
The vector connecting two WFs may be projected
to a line (\verb#one_dim#) or a plane (\verb#two_dim#).
The size of the projected vector
is calculated, and \verb#dist_cutoff# is applied.
When \verb#one_dim# or \verb#two_dim#
is used, \verb#one_dim_axis# must be given
to specify extended or confined direction.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#three_dim#  (default)
\item[{\bf --}] \verb#two_dim#
\item[{\bf --}] \verb#one_dim#
\end{itemize}

\subsection[one\_dim\_axis]{\tt character(len=20) :: one\_dim\_axis}

Extended direction for a one-dimensional system
or confined direction for a two-dimensional system.
This direction must be parallel to one of the Cartesian axes.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#x#
\item[{\bf --}] \verb#y#
\item[{\bf --}] \verb#z#
\end{itemize}

No default.


%\subsection[slice\_plot]{\tt logical :: slice\_plot}
%\red{Not yet implemented}
%
%If $\verb#slice_plot#=\verb#true#$ plot the wannier orbitals along
% slices in the super-unit-cell defined by \verb#slice_coord#.

%The default value of this parameter is false
%
%\subsection[slice\_coord]{slice\_coord}
%\red{Not yet implemented}
%
%\noindent \verb#begin slice_coord#
%$$
%\begin{array}{ccccccccc}
%O_x & O_y & O_x & X_x & X_y & X_z & Y_x & Y_y & Y_z \\
%\vdots
%\end{array}
%$$
%\verb#end slice_coord#
%
%Define the direction of the plotting slices. O is the origin. The slice
%is defined by the lines OX and OY.
%
%There is no default
%
%\subsection[slice\_num\_points]{\tt integer :: slice\_num\_points}
%\red{Not yet implemented}
%
%If $\verb#slice_plot#=\verb#true#$ the number of points in the first
%direction of the slice. The number of points in the second direction
%will be chosen to give the same density of points.
%
%The default value for \verb#slice_num_points# is 50
%
%
%\subsection[slice\_plot\_format]{\tt character(len=20) :: slice\_plot\_format}
%\red{Not yet implemented}
%
%Format in which to plot the interpolated bandstructure
%
%The valid options for this parameter are:
%\begin{itemize}
%\item[{\bf --}] gnuplot
%\item[{\bf --}] plotmtv
%\end{itemize}
%
%The default value for \verb#slice_plot_format# is gnuplot.


%\subsection[dos\_plot]{\tt logical :: dos\_plot}
%\red{Not yet implemented}
%
%If $\verb#dos_plot#=\verb#true#$ the code will calculate,
%through Wannier interpolation, the
%eigenvalues on a regular grid with dimension \verb#dos_num_points#. The
%density of states will be calculated by applying a Gaussian smearing of
%width \verb#dos_gaussian_width#.
%
%The default value of this parameter is false
%
%
%\subsection[dos\_num\_points]{\tt integer :: dos\_num\_points}
%\red{Not yet implemented}
%
%If $\verb#dos_plot#=\verb#true#$ the dimension of the k-point mesh
%to sample in calculating the density of states.
%
%The default value for \verb#dos_num_points# is 50
%
%\subsection[dos\_energy\_step]{\tt real(kind=dp) :: dos\_energy\_step}
%\red{Not yet implemented}
%
%The density of states will be calculated from the
%lowest to highest eigenenergies in the system. \verb#dos_energy_step# determines
%the size of the steps on the energy axis.
%
%The default value for \verb#dos_energy_step# is 0.02eV
%
%\subsection[dos\_gaussian\_width]{\tt real(kind=dp) :: dos\_gaussian\_width}
%\red{Not yet implemented}
%
%The width of the gaussian smearing to apply to each eigenenergy when
%calculating the dos.


%The default value for \verb#dos_gaussian_width# is 0.2eV
%
%\subsection[dos\_plot\_format]{\tt character(len=20) :: dos\_plot\_format}
%\red{Not yet implemented}
%
%Format in which to plot the density of states
%
%The valid options for this parameter are:
%\begin{itemize}
%\item[{\bf --}] gnuplot
%\item[{\bf --}] xmgrace
%\end{itemize}

%The default value for \verb#dos_plot_format# is gnuplot.