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

\section{Specification of projections in {\tt seedname.win}}
\label{sec:proj}
Here we describe the projection functions used to construct the
initial guess $A_{mn}^{(\mathbf{k})}$ for the unitary transformations.

Each projection is associated with a site and an angular momentum
state defining the projection function. Optionally, one may define,
for each projection, the spatial orientation, the radial part, the
diffusivity, and the volume over which real-space overlaps $A_{mn}$
are calculated.

The code is able to
\begin{enumerate}
\item project onto s,p,d and f
 angular momentum states, plus the hybrids sp, sp$^2$, sp$^3$, sp$^3$d,
 sp$^3$d$^2$.
\item control the radial part of the projection functions
  to allow higher angular momentum states, e.g., both 3s and 4s in
  silicon.
\end{enumerate}

The atomic orbitals of the hydrogen atom provide a good
basis to use for constructing the projection functions: analytical
mathematical forms exist in terms of the good quantum numbers $n$, $l$
and $m$; hybrid orbitals (sp, sp$^{2}$, sp$^{3}$, sp$^{3}$d etc.) 
can be constructed by simple linear combination $|\phi\rangle =
\sum_{nlm} C_{nlm}|nlm\rangle$ for some coefficients
$C_{nlm}$. 

The angular functions that use as a basis for the
projections are not the canonical spherical harmonics $Y_{lm}$ of the
hydrogenic Schr\"{o}dinger equation but rather the
\textit{real} (in the sense of non-imaginary) states
$\Theta_{lm_{\mathrm{r}}}$, obtained by a unitary
transformation. For example, the canonical
eigenstates associated with $l=1$, $m=\{-1,0,1\}$ are not 
the real p$_{x}$, p$_{y}$ and p$_{z}$
that we want. See Section~\ref{sec:orbital-defs} for our mathematical
conventions regarding projection orbitals for different $n$, $l$ and
$m_{\mathrm{r}}$.
 
We use the following format to specify projections in
\verb#<seedname>.win#:

\noindent
\verb#Begin Projections#\\
\verb#[units]#\\ 
%%\verb#site:ang_mtm:zaxis:xaxis:radial:zona:box-size#\\
\verb#site:ang_mtm:zaxis:xaxis:radial:zona#\\
\verb#    #\vdots\\
\verb#End Projections#

\noindent
Notes:

\noindent
\verb#units#:\\
Optional. Either \verb#Ang# or \verb#Bohr# to specify whether the
projection centres 
specified in this block (if given in Cartesian co-ordinates) are in
units of Angstrom or Bohr, respectively. The default value is \verb#Ang#.

\noindent
\verb#site#:\\
\verb#C#, \verb#Al#, etc. applies to all atoms of that type\\
\verb#f=0,0.50,0# -- centre on (0.0,0.5,0.0) in \textbf{f}ractional coordinates
(crystallographic units) relative to the direct lattice vectors \\
\verb#c=0.0,0.805,0.0# -- centre on (0.0,0.805,0.0) in \textbf{C}artesian
coordinates in units specified by the optional string \verb#units# in
the first line of the projections block (see above).

\noindent
\verb#ang_mtm#:\\
 Angular momentum states may be specified by \verb#l# and \verb#mr#,
 or by the appropriate character string. See Tables~\ref{tab:angular}
 and \ref{tab:hybrids}. Examples:\\
 \verb#l=2,mr=1 # or \verb# dz2# -- a single projection with $l=2$,
 $m_{\textrm{r}}=1$ (i.e., d$_{z^{2}}$)\\
 \verb#l=2,mr=1,4 # or \verb# dz2,dx2-y2# -- two functions: d$_{z^{2}}$ and d$_{xz}$\\
 \verb#l=-3 # or \verb# sp3# -- four sp$^{3}$ hybrids\\
 Specific hybrid orbitals may be specified as follows:\\
 \verb#l=-3,mr=1,3 # or \verb# sp3-1,sp3-3# -- two specific sp$^{3}$ hybrids\\
 Multiple states may be specified by separating with 
 `\verb#;#', e.g.,\\
 \verb#sp3;l=0 # or \verb# l=-3;l=0# -- four sp$^{3}$ hybrids and one s orbital

\noindent
\verb#zaxis# (optional):\\
\verb#z=1,1,1#  --  set the $z$-axis to be in the (1,1,1) direction. Default
is \verb#z=0,0,1# 

\noindent
\verb#xaxis# (optional):\\
\verb#x=1,1,1#  --  set the $x$-axis to be in the (1,1,1) direction. Default is
\verb#x=1,0,0#

\noindent
\verb#radial# (optional):\\
\verb#r=2#      --  use a radial function with one node (ie second highest
pseudostate with that angular momentum). Default is
\verb#r=1#. Radial functions associated with different values of
\verb#r# should be orthogonal to each other. 

\noindent
\verb#zona# (optional):\\
\verb#zona=2.0# -- the value of $\frac{Z}{a}$ for the radial part of the
atomic orbital (controls the diffusivity of the radial
function). Units always in reciprocal Angstrom. Default is \verb#zona=1.0#.

%%\noindent
%%\verb#box-size# (optional):\\
%%\verb#b=2.0# -- the linear dimension of the real-space
%%box (or sphere) for calculating the overlap
%%$\langle\psi_{m\mathbf{k}}|\phi_{n}\rangle$ of a wavefunction with the 
%%localised projection function. Units are always in Angstrom. Default
%%is \verb#b=1.0#. This feature is not currently used.


\noindent
\textbf{Examples}

1. CuO, s,p and d on all Cu; sp$^3$ hybrids on O:

\verb#Cu:l=0;l=1;l=2 #

\verb#O:l=-3 #  or  \verb# O:sp3#

2. A single projection onto a p$_z$ orbital orientated in the (1,1,1)
 direction:

\verb#c=0,0,0:l=1,mr=1:z=1,1,1 # or \verb# c=0,0,0:pz:z=1,1,1#

3. Project onto s, p and d (with no radial nodes), and s and p (with one
   radial node) in silicon:

\verb#Si:l=0;l=1;l=2#

\verb#Si:l=0;l=1:r=2#

\section{Spinor Projections}
When \verb#spinors=.true.# it is possible to select a set of localised
functions to project onto `up' states and a set to project onto `down'
states where, for complete flexibility, it is also possible to set the
local spin quantisation axis.

Note, however, that this feature requires a recent version of the 
interface between the ab-initio code and Wannier90 (i.e., written after
the release of the 2.0 version, in October 2013) supporting 
spinor projections. 

\noindent
\verb#Begin Projections#\\
\verb#[units]#\\ 
\verb#site:ang_mtm:zaxis:xaxis:radial:zona(spin)[quant_dir]#\\
\verb#    #\vdots\\
\verb#End Projections#

\noindent

\noindent
\verb#spin# (optional):\\
Choose projection onto `up' or `down' states\\
\verb#u#  --  project onto `up' states.\\
\verb#d#  --  project onto `down' states.\\
 Default is \verb#u,d# 


\noindent
\verb#quant_dir# (optional):\\
\verb#1,0,0#  --  set the spin quantisation axis to be in the (1,0,0) direction. Default
is \verb#0,0,1# 


\noindent
\textbf{Examples}
\begin{itemize}
\item 18 projections on an iron site

\verb#Fe:sp3d2;dxy;dxx;dyz#              

\item same as above

\verb#Fe:sp3d2;dxy;dxx;dyz(u,d)#
        
\item same as above

\verb#Fe:sp3d2;dxy;dxz;dyz(u,d)[0,0,1]#
  
\item same as above but quantisation axis is now x

\verb#Fe:sp3d2;dxy;dxz;dyz(u,d)[1,0,0]#

\item  now only 9 projections onto up states

\verb#Fe:sp3d2;dxy;dxz;dyz(u)#
           
\item 9 projections onto up-states and 3 on down

\verb#Fe:sp3d2;dxy;dxz;dyz(u) #\\
\verb#Fe:dxy;dxz;dyz(d)#                 

\item projections onto alternate spin states for two lattice sites (Cr1, Cr2)

\verb#Cr1:d(u)#\\
\verb#Cr2:d(d)#

\end{itemize}

\section{Short-Cuts}

\subsection{Random projections}

It is possible to specify the projections, for example, as follows:

\noindent
\verb#Begin Projections#\\
\verb#random#\\
\verb#C:sp3#\\
\verb#End Projections#

in which case \wannier\ uses four sp$^3$ orbitals centred on each C
atom and then chooses the appropriate number of randomly-centred
s-type Gaussian functions for the remaining projection functions. If
the block only consists of the string {\tt random} and no specific
projection centres are given, then all of the projection centres are
chosen randomly.


\subsection{Bloch phases}

Setting \verb#use_bloch_phases = true# in the input file absolves the
user of the need to specify explicit projections. In this case, the
Bloch wave-functions are used as the projection orbitals, namely
$A_{mn}^{(\mathbf{k})} =
\langle\psi_{m\mathbf{k}}|\psi_{n\mathbf{k}}\rangle = \delta_{mn}$.


\section{Orbital Definitions} \label{sec:orbital-defs}

The angular functions $\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$
associated with particular values of $l$ and $m_{\mathrm{r}}$ are given
in Tables~\ref{tab:angular} and \ref{tab:hybrids}. 

The radial functions $R_{\mathrm{r}}(r)$ associated with different values of
$r$ should be orthogonal. One choice would be to take the set of
solutions to the radial part of the hydrogenic Schr\"{o}dinger
equation for $l=0$, i.e., the radial parts of the 1s,
2s, 3s\ldots\ orbitals, which are given in Table~\ref{tab:radial}. 


\begin{table}
\begin{center}
\begin{tabular}{|cccc|}
\hline\hline
&&&\\
$l$ & $m_{\mathrm{r}}$ & Name & $\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$ \\ 
&&&\\\hline&&&\\
 0  &  1  &  \verb#s#   & $\frac{1}{\sqrt{4\pi}}$ \\ 
&&&\\\hline&&&\\
 1  &  1  &  \verb#pz#  & $\sqrt{\frac{3}{4\pi}}\cos\theta$ \\
&&&\\
 1  &  2  &  \verb#px#  & $\sqrt{\frac{3}{4\pi}}\sin\theta\cos\varphi$ \\
&&&\\
 1  &  3  &  \verb#py#  & $\sqrt{\frac{3}{4\pi}}\sin\theta\sin\varphi$ \\ 
&&&\\\hline&&&\\
 2  &  1  &  \verb#dz2# &
$\sqrt{\frac{5}{16\pi}}(3\cos^{2}\theta -1)$ \\
&&&\\
 2  &  2  &  \verb#dxz# &
$\sqrt{\frac{15}{4\pi}}\sin\theta\cos\theta\cos\varphi$ \\
&&&\\
 2  &  3  &  \verb#dyz# &
$\sqrt{\frac{15}{4\pi}}\sin\theta\cos\theta\sin\varphi$ \\
&&&\\
 2  &  4  &  \verb#dx2-y2# &
$\sqrt{\frac{15}{16\pi}}\sin^{2}\theta\cos2\varphi$ \\
&&&\\
 2  &  5  &  \verb#dxy# &
$\sqrt{\frac{15}{16\pi}}\sin^{2}\theta\sin2\varphi$ \\
&&&\\\hline&&&\\
 3  &  1  &  \verb#fz3# & 
$\frac{\sqrt{7}}{4\sqrt{\pi}}(5\cos^{3}\theta-3\cos\theta)$ \\
&&&\\
 3  &  2  &  \verb#fxz2# & 
$\frac{\sqrt{21}}{4\sqrt{2\pi}}(5\cos^{2}\theta-1)\sin\theta\cos\varphi$\\
&&&\\
 3  &  3  &  \verb#fyz2# & 
$\frac{\sqrt{21}}{4\sqrt{2\pi}}(5\cos^{2}\theta-1)\sin\theta\sin\varphi$\\
&&&\\
 3  &  4  &  \verb#fz(x2-y2)# & 
$\frac{\sqrt{105}}{4\sqrt{\pi}}\sin^{2}\theta\cos\theta\cos2\varphi$\\
&&&\\
 3  &  5  &  \verb#fxyz# & 
$\frac{\sqrt{105}}{4\sqrt{\pi}}\sin^{2}\theta\cos\theta\sin2\varphi$\\
&&&\\
 3  &  6  &  \verb#fx(x2-3y2)# & 
$\frac{\sqrt{35}}{4\sqrt{2\pi}}\sin^{3}\theta(\cos^{2}\varphi-3\sin^{2}\varphi)\cos\varphi$\\
&&&\\
 3  &  7  &  \verb#fy(3x2-y2)# & 
$\frac{\sqrt{35}}{4\sqrt{2\pi}}\sin^{3}\theta(3\cos^{2}\varphi-\sin^{2}\varphi)\sin\varphi$\\
&&&\\\hline\hline
\end{tabular}
\caption{Angular functions
$\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$
associated with particular values of $l$ and $m_{\mathrm{r}}$ for
$l\ge0$.
\label{tab:angular}}
\end{center}
\end{table}


\begin{table}
\begin{center}
\begin{tabular}{|cccc|}
\hline\hline
&&&\\
$l$ & $m_{\mathrm{r}}$ & Name & $\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$ \\ 
&&&\\\hline&&&\\
 $-$1  &  1  &  \verb#sp-1#   &  
$\frac{1}{\sqrt{2}}$\verb#s# $+\frac{1}{\sqrt{2}}$\verb#px# \\
&&&\\
 $-$1  &  2  &  \verb#sp-2#   &  
$\frac{1}{\sqrt{2}}$\verb#s# $-\frac{1}{\sqrt{2}}$\verb#px# \\
&&&\\\hline&&&\\
 $-$2  &  1  &  \verb#sp2-1#   &  
$\frac{1}{\sqrt{3}}$\verb#s# $-\frac{1}{\sqrt{6}}$\verb#px#
$+\frac{1}{\sqrt{2}}$\verb#py# \\  
&&&\\
 $-$2  &  2  &  \verb#sp2-2#   &  
$\frac{1}{\sqrt{3}}$\verb#s# $-\frac{1}{\sqrt{6}}$\verb#px#
$-\frac{1}{\sqrt{2}}$\verb#py# \\  
&&&\\
 $-$2  &  3  &  \verb#sp2-3#   &  
$\frac{1}{\sqrt{3}}$\verb#s# $+\frac{2}{\sqrt{6}}$\verb#px# \\
&&&\\\hline&&&\\
 $-$3  &  1  &  \verb#sp3-1#   &  
$\frac{1}{2}$(\verb#s# $+$ \verb#px# $+$ \verb#py# $+$ \verb#pz#) \\ 
&&&\\
 $-$3  &  2  &  \verb#sp3-2#   &  
$\frac{1}{2}$(\verb#s# $+$ \verb#px# $-$ \verb#py# $-$ \verb#pz#) \\ 
&&&\\
 $-$3  &  3  &  \verb#sp3-3#   &  
$\frac{1}{2}$(\verb#s# $-$ \verb#px# $+$ \verb#py# $-$ \verb#pz#) \\ 
&&&\\
 $-$3  &  4  &  \verb#sp3-4#   &  
$\frac{1}{2}$(\verb#s# $-$ \verb#px# $-$ \verb#py# $+$ \verb#pz#) \\ 
&&&\\\hline&&&\\
 $-$4  &  1  &  \verb#sp3d-1#  & 
$\frac{1}{\sqrt{3}}$\verb#s# $-\frac{1}{\sqrt{6}}$\verb#px#
$+\frac{1}{\sqrt{2}}$\verb#py#\\
&&&\\
 $-$4  &  2  &  \verb#sp3d-2#  &
$\frac{1}{\sqrt{3}}$\verb#s# $-\frac{1}{\sqrt{6}}$\verb#px#
$-\frac{1}{\sqrt{2}}$\verb#py#\\
&&&\\
 $-$4  &  3  &  \verb#sp3d-3#  &
$\frac{1}{\sqrt{3}}$\verb#s# $+\frac{2}{\sqrt{6}}$\verb#px#\\
&&&\\
 $-$4  &  4  &  \verb#sp3d-4#  & 
$\frac{1}{\sqrt{2}}$\verb#pz# $+\frac{1}{\sqrt{2}}$\verb#dz2#\\
&&&\\
 $-$4  &  5  &  \verb#sp3d-5#  & 
$-\frac{1}{\sqrt{2}}$\verb#pz# $+\frac{1}{\sqrt{2}}$\verb#dz2#\\
&&&\\\hline&&&\\
 $-$5  &  1  &  \verb#sp3d2-1# &   
$\frac{1}{\sqrt{6}}\verb#s#-\frac{1}{\sqrt{2}}\verb#px#
-\frac{1}{\sqrt{12}}\verb#dz2#+\frac{1}{2}\verb#dx2-y2#$ \\
&&&\\
 $-$5  &  2  &  \verb#sp3d2-2# &   
$\frac{1}{\sqrt{6}}\verb#s#+\frac{1}{\sqrt{2}}\verb#px#
-\frac{1}{\sqrt{12}}\verb#dz2#+\frac{1}{2}\verb#dx2-y2#$ \\
&&&\\
 $-$5  &  3  &  \verb#sp3d2-3# &   
$\frac{1}{\sqrt{6}}\verb#s#-\frac{1}{\sqrt{2}}\verb#py#
-\frac{1}{\sqrt{12}}\verb#dz2#-\frac{1}{2}\verb#dx2-y2#$ \\
&&&\\
 $-$5  &  4  &  \verb#sp3d2-4# &   
$\frac{1}{\sqrt{6}}\verb#s#+\frac{1}{\sqrt{2}}\verb#py#
-\frac{1}{\sqrt{12}}\verb#dz2#-\frac{1}{2}\verb#dx2-y2#$ \\
&&&\\
 $-$5  &  5  &  \verb#sp3d2-5# &   
$\frac{1}{\sqrt{6}}\verb#s#-\frac{1}{\sqrt{2}}\verb#pz#
+\frac{1}{\sqrt{3}}\verb#dz2#$ \\
&&&\\
 $-$5  &  6  &  \verb#sp3d2-6# &  
$\frac{1}{\sqrt{6}}\verb#s#+\frac{1}{\sqrt{2}}\verb#pz#
+\frac{1}{\sqrt{3}}\verb#dz2#$ \\
&&&\\\hline\hline
\end{tabular}
\caption{Angular functions
$\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$
associated with particular values of $l$ and $m_{\mathrm{r}}$ for
$l<0$, in terms of the orbitals defined in Table~\ref{tab:angular}.
\label{tab:hybrids}}
\end{center}
\end{table}


\begin{table}
\begin{center}
\begin{tabular}{|cc|}
\hline\hline
&\\
\ \ $r$ \ \ & $R_{\mathrm{r}}(r)$ \\
&\\\hline&\\
1        &  $2 \alpha^{3/2}\exp(-\alpha r)$ \\
&\\\hline&\\
2        &  $\frac{1}{2\sqrt{2}}\alpha^{3/2}(2-\alpha
r)\exp(-\alpha r/2)$ \\
&\\\hline&\\
3        &  $\sqrt{\frac{4}{27}}\alpha^{3/2}(1-2\alpha
r/3+2\alpha^{2}r^{2}/27)\exp(-\alpha r/3)$ \\
&\\\hline\hline
\end{tabular}
\caption{ One possible choice for the radial functions
  $R_{\mathrm{r}}(r)$ associated with different values of 
$r$: the set of
solutions to the radial part of the hydrogenic Schr\"{o}dinger
equation for $l=0$, i.e., the radial parts of the 1s,
2s, 3s\ldots\ orbitals, where $\alpha=Z/a={\tt zona}$. \label{tab:radial}}
\end{center}
\end{table}

\newpage

\section{Projections via the SCDM-\textbf{k} method in pw2wannier90}
For many systems, such as aperiodic systems, crystals with defects, or novel materials with complex band structure,  it may be extremely hard to identify \emph{a-priori} a good initial guess for the projection functions used to generate the $A_{mn}^{(\mathbf{k})}$ matrices. In these cases, one can use a different approach, known as the SCDM-\textbf{k} method\cite{LinLin-ArXiv2017}, based on a QR factorization with column pivoting (QRCP) of the density matrix from the self-consistent field calculation, which allows one to avoid the tedious step of specifying a projection block altogether, hence to avoid . This method is robust in generating well localised function with the correct spatial orientations and in general in finding the global minimum of the spread functional $\Omega$. Any electronic-structure code should in principle be able to implement the SCDM-\textbf{k} method within their interface with Wannier90, however at the moment (develop branch on the GitHub repository November 2017) only the QuantumEspresso package has this capability implemented in the pw2wannier90 interface program.
 The SCDM-\textbf{k} can operate in two modes: 
\begin{enumerate}
\item In isolation, i.e., without performing a subsequent Wannier90 optimisation (not recommended). This can be achieved by setting {\tt num\_iter=0} and {\tt dis\_num\_iter=0} in the \verb#<seedname>.win# input file. The rationale behind this is that in general the projection functions obtained with the SCDM-\textbf{k} are already well localised with the correct spatial orientations. However, the spreads of the resulting functions are usually larger than the MLWFs ones.  
\item In combination with the Marzari-Vanderbilt (recommended option). In this case, the SCDM-\textbf{k} is only used to generate the initial $A_{mn}^{(\mathbf{k})}$ matrices as a replacement scheme for the projection block.
\end{enumerate}

The following keywords need to be specified in the {\tt pw2wannier90.x} input file \verb#<seedname>.pw2wan#:
\noindent
\verb#scdm_proj#
\verb#scdm_entanglement#
\verb#scdm_mu#
\verb#scdm_sigma#
\noindent
