%!TEX root=./user_guide.tex
\chapter{\wannier\ as a library}\label{ch:wann-lib}

This is a description of the interface between any external program
and the wannier code. There are two subroutines: \verb#wannier_setup#
and \verb#wannier_run#. Calling \verb#wannier_setup# will return
information required to construct the $M_{mn}^{(\mathbf{k,b})}$
overlaps (Ref.~\cite{marzari-prb97}, Eq.~(25)) and
$A_{mn}^{(\mathbf{k})}=\left\langle
  \psi_{m\mathbf{k}}|g_{n}\right\rangle$ projections
(Ref.~\cite{marzari-prb97}, Eq.~(62); Ref.~\cite{souza-prb01},
Eq.~(22)). Once the overlaps and projection have been computed,
calling \verb#wannier_run# activates the minimisation and plotting
routines in \wannier.

\textbf{IMPORTANT NOTE:} the library mode ONLY works in serial. Please
call it from a serial code, or if compiled in parallel, make sure to run
it from a single MPI process.

You can find a minimal example of how the library mode can be used
among the tests, in the file 
\verb|test-suite/library-mode-test/test_library.F90| 
in the Wannier90 git repository.

%\section{Dependencies}
%\begin{itemize}
%\item Parameters
%\item IO
%\item Kmesh
%\item Overlap
%\item Wannierise
%\end{itemize}

\section{Subroutines}

\subsection{{\tt wannier\_setup}}

{\noindent \bf \verb#wannier_setup(seed_name,mp_grid,num_kpts,real_lattice,recip_lattice,#\\
\verb#              kpt_latt,num_bands_tot,num_atoms,atom_symbols,atoms_cart,#\\
\verb#              gamma_only,spinors,nntot,nnlist,nncell,num_bands,num_wann,proj_site,#\\
\verb#              proj_l,proj_m,proj_radial,proj_z,proj_x,proj_zona,#\\
\verb#              exclude_bands,proj_s,proj_s_qaxis)#}

\begin{itemize}
\item \verb#character(len=*), intent(in) :: seed_name#\\ The seedname
  of the current calculation.
\item \verb#integer, dimension(3), intent(in) :: mp_grid#\\ The
  dimensions of the {Monkhorst-Pack} k-point grid.
\item \verb#integer, intent(in) :: num_kpts#\\ The number of k-points on
  the {Monkhorst-Pack} grid.
\item \verb#real(kind=dp), dimension(3,3), intent(in) :: real_lattice#\\
  The lattice vectors in Cartesian co-ordinates in units of Angstrom.
\item \verb#real(kind=dp), dimension(3,3), intent(in) :: recip_lattice#\\
  The reciprocal lattice vectors in Cartesian co-ordinates in units of reciprocal Angstrom.
\item
  \verb#real(kind=dp), dimension(3,num_kpts), intent(in) :: kpt_latt#\\
  The positions of the k-points in fractional co-ordinates
  relative to the reciprocal lattice vectors.
\item \verb#integer, intent(in) :: num_bands_tot#\\ The total number of bands in the
first-principles calculation (note: including semi-core states).
\item \verb#integer, intent(in) :: num_atoms#\\ The total number of atoms
  in the system.
\item \verb#character(len=20), dimension(num_atoms),#
      \verb# intent(in) :: atom_symbols#\\ The elemental symbols of
      the atoms.
\item \verb#real(kind=dp), dimension(3,num_atoms),#
      \verb#intent(in) :: atoms_cart#\\ The positions of the atoms in
      Cartesian co-ordinates in Angstrom.
\item \verb#logical, intent(in) :: gamma_only#\\ Set to \texttt{.true.} if the
  underlying electronic structure calculation has been performed with
  only $\Gamma$-point sampling and, hence, if the Bloch eigenstates
  that are used to construct $A_{mn}^{(\mathbf{k})}$ and
  $M_{mn}^{\mathbf{(k,b)}}$ are real.
\item \verb#logical, intent(in) :: spinors#\\ Set to \texttt{.true.} if
  underlying electronic structure calculation has been performed with
  spinor wavefunctions. 
\item \verb#integer, intent(out) :: nntot#\\ The
  total number of nearest neighbours for each k-point. 
\item \verb#integer, dimension(num_kpts,num_nnmax),#
      \verb# intent(out) :: nnlist#\\
      The list of nearest neighbours for each k-point.
\item \verb#integer,dimension(3,num_kpts,num_nnmax),#
      \verb# intent(out) :: nncell#\\ 
      The vector, in fractional reciprocal lattice co-ordinates, that
      brings the \verb#nn#$^{\mathrm{th}}$ nearest neighbour of
      k-point \verb#nkp# to its periodic image that
      is needed for computing the overlap 
      $M_{mn}^{(\mathbf{k,b})}$.
\item \verb#integer, intent(out) :: num_bands#\\ The number of bands in the
first-principles calculation used to form the overlap matricies (note: excluding eg. semi-core states).
\item \verb#integer, intent(out) :: num_wann#\\ The number of MLWF
  to be extracted.
\item  \verb#real(kind=dp), dimension(3,num_bands_tot), intent(out) :: proj_site# \\
Projection function centre
in crystallographic co-ordinates relative to the direct lattice
vectors.
\item \verb#integer, dimension(num_bands_tot), intent(out) :: proj_l#\\
 $l$  specifies the angular part $\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$ of the
projection function  (see Tables~\ref{tab:angular}, \ref{tab:hybrids}
and \ref{tab:radial}). 
\item \verb#integer, dimension(num_bands_tot), intent(out) :: proj_m#\\
 $m_\mathrm{r}$ specifies the angular part $\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$, of the
projection function
 (see Tables~\ref{tab:angular}, \ref{tab:hybrids}
and \ref{tab:radial}). 
\item \verb#integer, dimension(num_bands_tot), intent(out) :: proj_radial#\\
$\mathrm{r}$ specifies the radial part $R_{\mathrm{r}}(r)$ of the
projection function 
(see Tables~\ref{tab:angular}, \ref{tab:hybrids}
and \ref{tab:radial}). 
\item  \verb#real(kind=dp), dimension(3,num_bands_tot), intent(out) :: proj_z#\\
Defines the axis from which the polar angle
$\theta$ in spherical polar coordinates is measured. Default is
\verb#0.0 0.0 1.0#.
\item  \verb#real(kind=dp), dimension(3,num_bands_tot), intent(out) :: proj_x#\\
Must be orthogonal to
\verb#z-axis#; default is \verb#1.0 0.0 0.0# or a vector
perpendicular to \verb#proj_z# if \verb#proj_z# is given; defines the
axis from with the azimuthal angle $\varphi$ in spherical polar
coordinates is measured.
\item \verb#real(kind=dp), dimension(num_bands_tot), intent(out) :: proj_zona#\\
The value of $\frac{Z}{a}$ associated
with the radial part of the atomic orbital. Units are in reciprocal
Angstrom.
\item \verb#integer, dimension(num_bands_tot), intent(out) :: exclude_bands#\\ 
      Kpoints independant list of bands to exclude from the
      calculation of the MLWF (e.g., semi-core states). 
\item \verb#integer, dimension(num_bands_tot), optional,intent(out) :: proj_s#\\
'1' or '-1' to denote projection onto up or down spin states
\item  \verb#real(kind=dp), dimension(3,num_bands_tot), intent(out) :: proj_s_qaxisx#\\
Defines the spin quantisation axis in Cartesian coordinates.

\end{itemize}

Conditions:
\begin{itemize}
\cond $\verb#num_kpts# = \verb#mp_grid(1)# \times \verb#mp_grid(2)#
\times \verb#mp_grid(3)#$.
\cond $\verb#num_nnmax# = 12$
\end{itemize}

This subroutine returns the information required to determine the
required overlap elements $M_{mn}^{(\mathbf{k,b})}$ and
projections $A_{mn}^{(\mathbf{k})}$,
i.e., \verb#M_matrix# and \verb#A_matrix#, described in
Section~\ref{wannier_run}. 

For the avoidance of doubt, \verb#real_lattice(1,2)# is the
$y-$component of the first lattice vector $\mathbf{A}_{1}$, etc.

The list of nearest neighbours of a particular k-point \verb#nkp# is
given by \verb#nnlist(nkp,1:nntot)#.

Additionally, the parameter \verb#shell_list#
may be specified in the \wannier\ input file.

\subsection{{\tt wannier\_run}} \label{wannier_run}

{\noindent \bf \verb#wannier_run(seed_name,mp_grid,num_kpts,real_lattice,recip_lattice,#\\
\verb#            kpt_latt,num_bands,num_wann,nntot,num_atoms,atom_symbols,#\\
\verb#            atoms_cart,gamma_only,M_matrix_orig,A_matrix,eigenvalues,#\\
\verb#            U_matrix,U_matrix_opt,lwindow,wann_centres,wann_spreads,#\\
\verb#            spread#)}

\begin{itemize}
\item \verb#character(len=*), intent(in) :: seed_name#\\ The seedname
  of the current calculation.
\item \verb#integer, dimension(3), intent(in) :: mp_grid#\\ The
  dimensions of the {Monkhorst-Pack} k-point grid.
\item \verb#integer, intent(in) :: num_kpts#\\ The number of k-points on
  the {Monkhorst-Pack} grid.
\item \verb#real(kind=dp), dimension(3,3),#
      \verb# intent(in) :: real_lattice#\\ The lattice vectors in
      Cartesian co-ordinates in units of Angstrom. 
\item \verb#real(kind=dp), dimension(3,3), intent(in) :: recip_lattice#\\
  The reciprical lattice vectors in Cartesian co-ordinates in units of inverse Angstrom.
\item \verb#real(kind=dp), dimension(3,num_kpts),#
      \verb# intent(in) :: kpt_latt#\\ The positions of the k-points in
      fractional co-ordinates relative to the reciprocal lattice
      vectors.
\item \verb#integer, intent(in) :: num_bands#\\ The total number of
      bands to be processed.
\item \verb#integer, intent(in) :: num_wann#\\ The number of MLWF to
  be extracted. 
\item \verb#integer, intent(in) :: nntot#\\ The number of
  nearest neighbours for each k-point.
\item \verb#integer, intent(in) :: num_atoms#\\ The total number of atoms
  in the system.
\item \verb#character(len=20), dimension(num_atoms),#
      \verb# intent(in) :: atom_symbols#\\ The elemental symbols of
      the atoms.
\item \verb#real(kind=dp), dimension(3,num_atoms),#
      \verb#intent(in) :: atoms_cart#\\ The positions of the atoms in
      Cartesian co-ordinates in Angstrom.
\item \verb#logical, intent(in) :: gamma_only#\\ Set to \texttt{.true.} if the
  underlying electronic structure calculation has been performed with
  only $\Gamma$-point sampling and, hence, if the Bloch eigenstates
  that are used to construct $A_{mn}^{(\mathbf{k})}$ and
  $M_{mn}^{\mathbf{(k,b)}}$ are real.
\item \verb#complex(kind=dp),#
      \verb# dimension(num_bands,num_bands,nntot,num_kpts),#\\
      \verb#                  intent(in) :: M_matrix#\\ 
      The matrices of overlaps between neighbouring periodic parts of
      the Bloch eigenstates at each k-point, $M_{mn}^{(\mathbf{(k,b)})}$
      (Ref.~\cite{marzari-prb97}, Eq.~(25)).
\item \verb#complex(kind=dp), dimension(num_bands,num_wann,num_kpts),#\\
      \verb#                  intent(in) :: A_matrix# \\The matrices
      describing the projection of \verb#num_wann# trial orbitals on
      \verb#num_bands# Bloch states at each k-point,
      $A_{mn}^{(\mathbf{k})}$ (Ref.~\cite{marzari-prb97}, Eq.~(62);
      Ref.~\cite{souza-prb01}, Eq.~(22)).
\item \verb#real(kind=dp), dimension(num_bands,num_kpts),#
      \verb#intent(in) :: eigenvalues#\\ The
      eigenvalues $\varepsilon_{n\mathbf{k}}$ corresponding to the
      eigenstates, in eV.
\item \verb#complex(kind=dp), dimension(num_wann,num_wann,num_kpts),#\\
      \verb#                  intent(out) :: U_matrix#\\ The unitary
      matrices at each k-point (Ref.~\cite{marzari-prb97}, Eq.~(59))
\item \verb#complex(kind=dp), dimension(num_bands,num_wann,num_kpts),#\\
      \verb#               optional, intent(out) :: U_matrix_opt#\\ The
      unitary matrices that describe the optimal sub-space at each
      k-point (see Ref.~\cite{souza-prb01}, Section~{\sc IIIa}). The array is
      packed (see below) 
\item \verb#logical, dimension(num_bands,num_kpts), optional, intent(out) :: lwindow#\\ 
       The element \verb#lwindow(nband,nkpt)# is {\tt .true.} if the band
{\tt nband} lies within the outer energy window at kpoint {\tt nkpt}.
\item \verb#real(kind=dp), dimension(3,num_wann), optional, intent(out) :: wann_centres#\\   
      The centres of the MLWF in Cartesian co-ordinates in Angstrom. 
\item \verb#real(kind=dp), dimension(num_wann), optional, intent(out) :: wann_spreads#\\ 
      The spread of each MLWF in \AA$^{2}$.
\item \verb#real(kind=dp), dimension(3), optional, intent(out) ::#
      \verb#spread#\\ 
      The values of $\Omega$, $\Omega_{\mathrm{I}}$ and
      $\tilde{\Omega}$ (Ref.~\cite{marzari-prb97}, Eq.~(13)). 
\end{itemize}

Conditions:
\begin{itemize}
\cond $\verb#num_wann# \le \verb#num_bands#$
\cond $\verb#num_kpts# = \verb#mp_grid(1)# \times \verb#mp_grid(2)#
\times \verb#mp_grid(3)#$.
\end{itemize}

If $\verb#num_bands# = \verb#num_wann#$ then \verb#U_matrix_opt# is the identity matrix and
\verb#lwindow=.true.#

For the avoidance of doubt, \verb#real_lattice(1,2)# is the
$y-$component of the first lattice 
vector $\mathbf{A}_{1}$, etc.

\begin{eqnarray*}
\verb#M_matrix(m,n,nn,nkp)# & = & \left\langle u_{m\mathbf{k}} |
u_{n\mathbf{k+b}}\right\rangle\\
\verb#A_matrix(m,n,nkp)# & = &
\left\langle \psi_{m\mathbf{k}}|g_{n}\right\rangle\\
\verb#eigenvalues(n,nkp)# &=& \varepsilon_{n\mathbf{k}}
\end{eqnarray*}
where
\begin{eqnarray*}
\mathbf{k} &=&\verb#kpt_latt(1:3,nkp)#\\
\mathbf{k+b}&=& \verb#kpt_latt(1:3,nnlist(nkp,nn))# +
\verb#nncell(1:3,nkp,nn)# 
\end{eqnarray*}
and
$\left\{|g_{n}\rangle\right\}$ are a set of initial trial
orbitals. These are
typically atom or bond-centred Gaussians that are modulated by
appropriate spherical harmonics. 

Additional parameters should be specified in the \wannier\ input
file.

