Add docs for PDWF

doc/tutorial/tutorial.tex

@@ -3947,7 +3947,7 @@ \subsection*{Further ideas}
 
 \begin{enumerate}
   \item Try changing the {\tt atom\_proj\_exclude} in {\tt silicon.pw2wan} file,
-  i.e., these the commented lines
+  i.e., these commented lines
   {\tt
   \begin{quote}
     ! for excluding specific projectors\\
@@ -3961,6 +3961,19 @@ \subsection*{Further ideas}
   \item Now that $3d$ projectors provide us a larger space for optimization, you
   can try increasing the \verb#dis_froz_max# to freeze higher energy bands, if
   you are targeting at reproducing those eigenvalues.
+
+  Note that the \verb#dis_proj_min/max# and \verb#dis_froz_min/max# can be
+  enabled simultaneously: the union of inner energy window and
+  high-projectability states will be freezed, and the union of states outside
+  outer energy window and having low projectability will be discared.
+  Thus, you can still use energy window to make sure near-Fermi energy states
+  are well reproduced, and use ``projectability window'' to selectively
+  freeze atomic-like states in the conduction region.
+
+  \item The default \verb|dis_proj_max = 0.95| might not freeze all the states you want, try changing this value
+  and see the band interpolation results.
+  For other materials, it might worth trying decreasing
+  this value to freeze more states.
 \end{enumerate}
 
 %\cleardoublepage

doc/user_guide/overview.tex

@@ -111,7 +111,8 @@ \section*{Credits}
 Matthew Shelley (transport routines),
 Christian Stieger (routine to print the U matrices),
 David Strubbe (various bugfixes/improvements),
-Timo Thonhauser (extension of pw2wannier90 to add terms needed for orbital magnetisation), Junfeng Qiao (spin Hall conductivity).
+Timo Thonhauser (extension of pw2wannier90 to add terms needed for orbital magnetisation),
+Junfeng Qiao (spin Hall conductivity, projectability-disentangled Wannier functions).
 
 We also acknowledge individuals not already mentioned above who participated in the first Wannier90 community meeting (San Sebastian, 2016) for useful discussions:
 Daniel Fritsch,

doc/user_guide/parameters.tex

@@ -162,6 +162,9 @@ \section{Keyword List}
 {\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\_froz\_proj }   & L & To activate projectability disentanglement \\
+{\sc dis\_proj\_min }   & P & Lower threshold for projectability disentanglement \\
+{\sc dis\_proj\_max }   & P & Upper threshold for projectability disentanglement \\
 {\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$\\
@@ -862,6 +865,47 @@ \section{Disentanglement}
 
 No default.
 
+\subsection[dis\_froz\_proj]{\tt logical :: dis\_froz\_proj}
+To activate projectability disentanglement procedure, which selectively
+discard/disentangle/freeze state $\ket{n \mathbf{k}}$ based on its projectability
+onto some localized atomic orbitals.
+
+Note: this requires the \verb#amn# file is properly normalized, i.e.,
+projectability computed from $A A^\dagger$ must be smaller than or equal to 1.
+The pseudo-atomic projection satisfies such requirement, see \ref{sec:proj_pdwf}.
+
+Additionally, one can combine projectability disentanglement with energy
+disentanglement, i.e., enable both \verb#dis_proj_min/max# and
+\verb#dis_froz_min/max# simultaneously in the \verb#win# file.
+These settings will freeze the union of inner energy window and
+high-projectability states, and exclude the union of states outside
+outer energy window and having low projectability.
+
+\subsection[dis\_proj\_min]{\tt real(kind=dp) :: dis\_proj\_min}
+The lower bound for the projectability disentanglement procedure.
+
+For states with projectabilities smaller than \verb#dis_proj_min#, they
+will be discarded in the disentanglement procedure, i.e., similar to the case
+of outside of the outer energy window.
+
+For states with projectabilities larger than or equal to \verb#dis_proj_min#,
+they will be included in the disentanglement procedure, i.e., similar to the
+case of inside the outer energy window.
+
+No unit.
+
+The default value is 0.95.
+
+\subsection[dis\_proj\_max]{\tt real(kind=dp) :: dis\_proj\_max}
+The upper bound for the projectability disentanglement procedure.
+For states with projectability larger than or equal to \verb#dis_proj_max#, they
+will be freezed in the disentanglement procedure, i.e., similar to the case of
+inside the inner energy window.
+
+No unit.
+
+The default value is 0.01.
+
 \subsection[dis\_num\_iter]{\tt integer :: dis\_num\_iter}
 In the disentanglement procedure, the
 number of iterations used to extract the most connected subspace.

doc/user_guide/projections.tex

@@ -442,3 +442,107 @@ \section{Projections via the SCDM-\textbf{k} method in pw2wannier90}
 \verb#scdm_mu#
 \verb#scdm_sigma#
 \noindent
+
+\section{Projections via pseudo-atomic orbitals in pw2wannier90} \label{sec:proj_pdwf}
+
+When generating pseudopotentials, often the atomic wavefunctions of isolated atom
+are pseudized and bundled together with the pseudopotential files.
+These orbitals are often used for computing the projectabilities, for instance,
+measuring orbital contributions to band structures.
+Instead of manually specifying the initial projections in the \verb#projections#
+block, one can use these pseudo-atomic orbitals to automate the initial projection
+process.
+
+Currently (July 2023), this functionality is implemented in the \QE{} interface, but
+in principle it can be done in any other interface as well.
+In the following, we will use the \QE{} interface as an example to illustrate
+the whole procedure.
+
+To activate pseudo-atomic orbital projection, one needs to set
+\verb#auto_projections = .true.# in
+the \verb#win# file, and remove the \verb#projections# block.
+
+Then in the \verb#pw2wannier90# input file, one needs to add an additional
+tag \verb#atom_proj = .true.#. This will ask \verb#pw2wannier90# to read the
+pseudo-atomic orbitals from the pseudopotential files, and use them to compute
+the \verb#amn# file.
+
+Some times, one may want to exclude semi-core states from Wannierisation, for
+such cases, one can inspect the stdout of \verb#pw2wannier90#, which will print
+the orbitals used for computing \verb#amn#, e.g.,
+
+{\tt
+\begin{quote}
+-------------------------------------\\
+*** Compute  A with atomic projectors\\
+-------------------------------------\\
+Use atomic projectors from UPF\\
+\\
+   (read from pseudopotential files):\\
+   state \#   1: atom   1 (C  ), wfc  1 (l=0 m= 1)\\
+   state \#   2: atom   1 (C  ), wfc  2 (l=1 m= 1)\\
+   state \#   3: atom   1 (C  ), wfc  2 (l=1 m= 2)\\
+   state \#   4: atom   1 (C  ), wfc  2 (l=1 m= 3)\\
+   state \#   5: atom   2 (C  ), wfc  1 (l=0 m= 1)\\
+   state \#   6: atom   2 (C  ), wfc  2 (l=1 m= 1)\\
+   state \#   7: atom   2 (C  ), wfc  2 (l=1 m= 2)\\
+   state \#   8: atom   2 (C  ), wfc  2 (l=1 m= 3)\\
+\end{quote}
+}
+
+Here it shows that there are two carbon atoms, each with one $s$ and three $p$
+orbitals. If one wants to exclude specific orbital(s), there is an additional
+input \verb#atom_proj_exclude#, which accept a list of integers, e.g.,
+
+{\tt atom\_proj\_exclude = 1 5}
+
+which will exclude the two $s$ orbitals from computing \verb#amn#.
+
+\subsubsection*{Advanced usage}
+If the pseudopotential orbitals are not enough, one could also generate a
+custom set of orbitals, and ask \verb#pw2wannier90# to use them for computing
+\verb#amn#. This can be done by setting
+
+{\tt atom\_proj\_dir = './ext\_proj'}
+
+where the directory \verb#ext_proj# contains the orbitals for all the atomic
+species used in the calculation. For example, for a silicon calculation, the
+directory \verb#ext_proj# should contain a file named \verb#Si.dat#.
+The format of the file is:
+\begin{enumerate}
+  \item The first line contains two integers: the number of radial grid points ($n_g$)
+  and the number of projectors ($n_p$), e.g.,
+  \begin{verbatim}
+1141 2
+  \end{verbatim}
+  which means the radial grid has $n_g = 1141$ points, and there are $n_p = 3$ projectors.
+
+  \item The second line contains $n_p$ integers specifying the angular momentums
+  of all the projectors, e.g.,
+  \begin{verbatim}
+0 1
+  \end{verbatim}
+  standing for the two projectors having $s$ and $p$ characters, respectively.
+
+  \item The rest of the file contains $n_g$ rows of the radial wavefunctions of the projectors. There are $2+n_p$ columns: the first
+  column is the $x$-grid, the second column is the $r$-grid
+  in Bohr unit,
+  and they are related by $r = \exp(x)$. The rest are
+  $n_p$ columns of the radial wavefunctions of the projectors,
+  \begin{verbatim}
+-9.639057329615259 0.000065134426111 3.32211124436945e-05 1.86840239681223e-09
+-9.626557329615258 0.000065953716334 3.363898259696903e-05 1.915701228607072e-09
+-9.614057329615258 0.000066783311958 3.406210890972733e-05 1.964197436025957e-09
+...
+  \end{verbatim}
+
+  Inside \verb#pw2wannier90.x#, the radial wavefunction will be read and multiplied by spherical
+  harmonics to form the actual projectors.
+
+  For a practical example of extracting pseudo-atomic orbitals
+  from UPF file and writing to a \verb#pw2wannier90#-recognizable \verb#.dat# file, see the script
+  \verb#utility/write_pdwf_projectors.py#.
+
+  For an actual example of a \verb#Si.dat# file for silicon,
+  see the file \verb#examples/example35/ext_proj/Si.dat#.
+\end{enumerate}

doc/user_guide/utilities.tex

@@ -302,4 +302,22 @@ \section{$\tt{w90spn2spn.x}$\label{sec:w90spn2spn}}
 you do not want to rerun \texttt{pw2wannier90.x}, then 
 \texttt{w90spn2spn.x} can be useful. 
 Also, once a ``formatted'' \verb|seedname.spn| has been generated, the step 4 can be skipped if 
-\texttt{spn\_formatted} is set to \texttt{true} in \postw\ input file \verb|seedname.win|.
+\texttt{spn\_formatted} is set to \texttt{true} in \postw\ input file \verb|seedname.win|.
+
+\section{{\tt write\_pdwf\_projectors.py}}
+
+A python script to extract projectors from a \verb#UPF# file
+and write them into a \verb#pw2wannier90.x#-recognizable
+\verb#dat# file, which can be used to compute \verb#amn# using pseudo-atomic orbital
+projection.
+
+Usage:\newline
+
+\verb|path/write_pdwf_projectors.py UPF_filename|\newline
+
+where \verb|path| is the path of \verb|utility| folder,
+\verb|UPF_filename| is the path of a \verb#UPF# file.
+
+The script serves as a reference for writing the \verb#dat# file,
+you can generate your own pseudo-atomic orbitals by some other
+codes and use them to compute \verb#amn#.

doc/user_guide/wannier-pp.tex

@@ -226,6 +226,9 @@ \subsection{\label{sec:auto-projections-block}{\tt auto\_projections} block}
 
 Moreover, also the automatic generation of initial projections with spinor WFs is implemented in the {\tt pw2wannier90} interface. See Example 31 in the \wannier\ tutorial that shows how to use it.
 
+Another automatic projection method is projectability-disentangled Wannier function (PDWF) \cite{Qiao2023-pdwf}, which uses pseudo-atomic orbitals inside pseudopotentials as initial guesses.
+See Example 34 and 35.
+
 
 
 \subsection{An example of projections}\label{sec:proj_example}
@@ -575,6 +578,14 @@ \subsection{{\tt seedname.pw2wan}}
 (only relevant if \verb#write_dmn=.true.#). 
 
 
+\item \verb#atom_proj# -- Set to \verb#.true.# to use pseudo-atomic orbitals for computing \verb#amn#. Default is \verb#.false.#.
+
+\item \verb#atom_proj_exclude# -- A list of integers specifying the indices of pseudo-atomic projectors to be excluded from computing \verb#amn#. Used only when \verb#atom_proj = .true.#. No default.
+
+\item \verb#atom_proj_ext# -- Set to \verb#.true.# to use external pseudo-atomic orbitals for computing \verb#amn#, will read data files from directory \verb#atom_proj_dir#. Used only when \verb#atom_proj = .true.#. Default is \verb#.false.#.
+
+\item \verb#atom_proj_dir# -- A string specifying the directory for external pseudo-atomic projectors. Used only when \verb#atom_proj = .true.# and \verb#atom_proj_ext = .true.#. No default.
+
 
 \end{itemize}