Skip to content

Commit

Permalink
Merge pull request wannier-developers#238 from VVitale/move_SCDM_to_p…
Browse files Browse the repository at this point in the history 
…w2wannier90

Move SCDM flags to pw2wannier90
  • Loading branch information
@giovannipizzi
giovannipizzi authored Feb 24, 2019
2 parents 827a716 + 16b00f1 commit 375d5ee
Show file tree
Hide file tree
Showing 16 changed files with 5,254 additions and 275 deletions.
30 changes: 13 additions & 17 deletions doc/tutorial/tutorial.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2892,7 +2892,7 @@ \subsection*{Shift current $\sigma^{abc}$}

\sectiontitle{27: Silicon -- Selected columns of density matrix algorithm for automated MLWFs}

Note: This example requires a recent version of the {\tt pw2wannier90.x} post-processing code of {\tt Quantum ESPRESSO}.
Note: This example requires a recent version of the {\tt pw2wannier90.x} post-processing code of {\tt Quantum ESPRESSO} (v6.4 or above).

\begin{itemize}
\item{Outline: \it{For bulk crystalline Silicon, generate the $A_{mn}$ matrices via the selected columns of density matrix (SCDM) algorithm and the corresponding MLWFs for 1) Valence bands 2) Valence bands and 4 low-lying conduction bands 3) Conduction bands only. To better understand the input files and the results of these calculations, it is crucial that the Reader has familiarized with the concepts and methods explained in Ref.~\cite{LinLin-ArXiv2017}. More info on the keywords related to the SCDM method may be found in the user\_guide.}}
Expand All @@ -2906,9 +2906,8 @@ \subsection*{Shift current $\sigma^{abc}$}
states on a uniform grid for 4 bands.}}
\item{ {\tt si\_12bands.nscf } {\it The \pwscf\ input file to obtain Bloch
states on a uniform grid for 12 bands.}}
\item{ {\tt silicon.pw2wan} {\it The input file for {\tt pw2wannier90}}}
\end{itemize}
\item{ Whereas the three subfolders {\tt isolated, erfc} and {\tt gaussian} contain the {\tt si.win} \wannier~ input files each corresponding to one of the situations described in the outline.}
\item{ Whereas the three subfolders {\tt isolated, erfc} and {\tt gaussian} contain the {\tt si.win} \wannier~ input files and {\tt si.pw2wan} {\tt pw2wannier90} input files each corresponding to one of the scenarios listed in the outline.}
\end{itemize}


Expand All @@ -2922,20 +2921,13 @@ \subsection*{Shift current $\sigma^{abc}$}
\item Run \pwscf\ to obtain the Bloch states on a uniform k-point grid of 4x4x4 for 4 bands. \\
{\tt pw.x < si\_4bands.nscf > nscf.out}

\item Inspect the \wannier input file. You will find two new keywords, i.e. {\tt scdm\_proj} and {\tt scdm\_entanglement}. The former, will instruct the pw2wannier90 code whether to use the SCDM method or not when generating the $A_mn$ matrix. This information is stored in the {\tt .nnkp} file that you will generate. The latter, defines which formula to adopt for the function $f(\varepsilon_{n\mathbf{k}})$ (see \cite{LinLin-ArXiv2017} and point below).
\item Inspect the {\tt si.win} input file and make sure that the {\tt auto\_projections} flag is set to {\tt .true.}. Also, make sure that no projections block is present.
\item Run \wannier\ to generate a list of the required overlaps and also info on the SCDM method (written
into the {\tt si.nnkp} file).\\
{\tt wannier90.x -pp si}
\item Check the {\tt si.nnkp} file and make sure you find the following block for the SCDM method
\begin{verbatim}
begin scdm_info
1
4
0
0.00000 1.00000
end scdm_info
\end{verbatim}
\item Inspect the {\tt si.nnkp} file and make sure you find the {\tt auto\_projections} block and that no projections have been written in the {\tt projections} block.

\item Inspect the {\tt .pw2wan} input file. You will find two new keywords, i.e. {\tt scdm\_proj} and {\tt scdm\_entanglement}. The former, will instruct {\tt pw2wannier90.x} to use the SCDM method when generating the $A_{mn}$ matrix. The latter, defines which formula to adopt for the function $f(\varepsilon_{n\mathbf{k}})$ (see \cite{LinLin-ArXiv2017} and point below).
\item Run {\tt pw2wannier90} to compute the overlap between Bloch
states and the projections via the SCDM method (written in the
{\tt si.mmn} and {\tt si.amn} respectively).\\
Expand All @@ -2946,7 +2938,7 @@ \subsection*{Shift current $\sigma^{abc}$}
At this point, you should have obtained 4 Wannier functions and the interpolated valence bands for Silicon. Inspect the output file {\tt si.wout}. In particular, look at the geometric centres of each WF, do they lie at the centre of the Si-Si bond as for the MLWFs computed from user-defined initial $s$-like projections (see Example11)?
Plot these WFs using Vesta. Do they show the $\sigma$ character one would expect from chemical arguments?
\end{enumerate}
\item[2]{Valence bands + conduction bands: In this case we will compute 8 localized WFs corresponding to the 4 valence bands and 4 low-lying conduction bands. Here, we don't have a separate manifold, since the conduction bands are entangled with other high-energy bands and the columns of the density matrix are not exponentially localized by construction. A modified density matrix is required defined as\cite{LinLin-ArXiv2017}: $$P(\mathbf{r},\mathbf{r}') = \sum_{n,\mathbf{k}} \psi_{n\mathbf{k}}(\mathbf{r})f(\varepsilon_{n,\mathbf{k}})\psi_{n\mathbf{k}}^\ast(\mathbf{r}'),$$
\item[2]{Valence bands + conduction bands: In this case we will compute 8 localized WFs corresponding to the 4 valence bands and 4 low-lying conduction bands. Here, we don't have a separate manifold, since the conduction bands are entangled with other high-energy bands and the columns of the density matrix are not exponentially localized by construction. A modified density matrix is required in this case\cite{LinLin-ArXiv2017}, and it is defined as: $$P(\mathbf{r},\mathbf{r}') = \sum_{n,\mathbf{k}} \psi_{n\mathbf{k}}(\mathbf{r})f(\varepsilon_{n,\mathbf{k}})\psi_{n\mathbf{k}}^\ast(\mathbf{r}'),$$
where $\psi_{n\mathbf{k}}$ and $\varepsilon_{n,\mathbf{k}}$ are the energy eigestates and eigenvalues from the first-principle calculation respectively. The function $f(\varepsilon_{n,\mathbf{k}})$ contains two free parameters $\mu$ and $\sigma$ and is defined as a complementary error function: $$f(\varepsilon_{n,\mathbf{k}}) = \frac{1}{2}\mathrm{erfc}\left(\frac{\varepsilon_{n,\mathbf{k}} - \mu}{\sigma}\right).$$ }
\begin{enumerate}
\item Copy the input files {\tt si.scf, si\_12bands.nscf} and {\tt si.pw2wan} from the {\tt input\_files} folder into the {\tt erfc} folder
Expand All @@ -2956,11 +2948,13 @@ \subsection*{Shift current $\sigma^{abc}$}
\item Run \pwscf\ to obtain the Bloch states on a uniform k-point grid of 4x4x4 for 12 bands this time. \\
{\tt pw.x < si\_12bands.nscf > nscf.out}

\item Inspect the \wannier input file. You will find other two new keywords, i.e. {\tt scdm\_mu} and {\tt scdm\_sigma}. These are the values in eV of $\mu$ and $\sigma$ in $f(\varepsilon_{n,\mathbf{k}})$, respectively. They are read by pw2wannier90 from the SCDM block in the {\tt .nnkp} file (last line).
\item Run \wannier\ to generate a list of the required overlaps and info on the SCDM method (written
\item Inspect the {\tt si.win} input file and make sure that the {\tt auto\_projections} flag is set to {\tt .true.}. Also, make sure that no projection block is present.
\item Run \wannier\ to generate a list of the required overlaps and also info on the SCDM method (written
into the {\tt si.nnkp} file).\\
{\tt wannier90.x -pp si}
\item Inspect the {\tt si.nnkp} file and make sure you find the {\tt auto\_projections} block and that no projections have been written in the {\tt projections} block.

\item Inspect the {\tt .pw2wan} input file. You will find other two new keywords, i.e. {\tt scdm\_mu} and {\tt scdm\_sigma}. These are the values in eV of $\mu$ and $\sigma$ in $f(\varepsilon_{n,\mathbf{k}})$, respectively.
\item Run {\tt pw2wannier90} to compute the overlap between Bloch
states and the projections via the SCDM method (written in the
{\tt si.mmn} and {\tt si.amn} respectively).\\
Expand All @@ -2979,9 +2973,11 @@ \subsection*{Shift current $\sigma^{abc}$}
\item Run \pwscf\ to obtain the Bloch states on a uniform k-point grid of 4x4x4 for 12 bands this time. \\
{\tt pw.x < si\_12bands.nscf > nscf.out}

\item Run \wannier\ to generate a list of the required overlaps (written
\item Inspect the {\tt si.win} input file and make sure that the {\tt auto\_projections} flag is set to {\tt .true.}. Also, make sure that no projections block is present.
\item Run \wannier\ to generate a list of the required overlaps and also info on the SCDM method (written
into the {\tt si.nnkp} file).\\
{\tt wannier90.x -pp si}
\item Inspect the {\tt si.nnkp} file and make sure you find the {\tt auto\_projections} block and that no projections have been written in the {\tt projections} block.

\item Run {\tt pw2wannier90} to compute the overlap between Bloch
states, the projections for the starting guess via the SCDM method (written in the
Expand Down
78 changes: 45 additions & 33 deletions doc/user_guide/parameters.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ \section{Keyword List}
%{\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 \\
Expand Down Expand Up @@ -221,11 +222,6 @@ \section{Keyword List}
{\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 scdm\_proj} & L & Whether to use the SCDM-k method of Ref.~\cite{LinLin-ArXiv2017} \\
{\sc scdm\_entanglement} & I & The entanglement method to use in SCDM-k \\
{\sc scdm\_mu} & P & The value of the parameter $\mu$ in SCDM-k \\
{\sc scdm\_sigma} & P & The value of the parameter $\sigma$ in SCDM-k \\
%% AAM: rename all of these slwf_*
{\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 \\
Expand Down Expand Up @@ -623,8 +619,8 @@ \subsection{Shells}
\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.
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.

Expand Down Expand Up @@ -743,6 +739,21 @@ \section{Job Control}

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

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

If {\tt .true.} and no projections block is defined than \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})}$. The {\tt auto\_projections} block has the following syntax

\noindent \verb#begin auto_projections# \\
\verb# num_wannier# \\
\verb# 0# \\
\verb#end auto_projections#

The choice of an additional block has been made in order to maintain back-compatibility with codes that interface with \wannier, e.g. {\tt pw2wannier90}.
The first entry in the block is the total number of target projections and it is equal to the number of sought Wannier functions.
The second entry is a reserved flag for the time being and must be zero. In the future, we plan to combine the automatic generation of initial projections with the selection of projections via a projections block. This will allow the User to specify only a subset of initial projections in the projections block and leave the interface code to automatically generate the remaining ones. In that case the constraint on the second entry will be lift, so that it can take on the meaning of the number of projections that need to be generated automatically.
The selected columns of the density matrix (SCDM) method\cite{LinLin-ArXiv2017} is one way of generating the initial $A_{mn}^{(\mathbf{k})}$ in an automatic way. This has been implemented in the {\tt pw2wannier90} interface code (you need v6.4 or above), see for instance Example 27 in the \wannier\ tutorial that shows how to use it.
N.B. Automatic generation of initial projections is not compatible with spinor-WFs yet.

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

If \verb#restart# is present the code will attempt to restart the calculation
Expand Down Expand Up @@ -1094,32 +1105,33 @@ \section{Wannierise}\label{sec:wann_params}

The default value is 1.0E-3.

\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}.
% 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} $\le$ {\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.
Expand Down
Loading

0 comments on commit 375d5ee

Please sign in to comment.