Merge branch 'develop' into 191015

Makefile

@@ -8,6 +8,18 @@ TAR := $(shell if which gnutar 1>/dev/null 2> /dev/null; then echo gnutar; else
 
 default: wannier post
 
+PREFIX ?= /usr
+
+install: default
+	install -d $(DESTDIR)$(PREFIX)/bin/
+	for x in wannier90.x postw90.x w90chk2chk.x w90spn2spn.x ; do \
+		if [ -f "$$x" ]; then install -m755 "$$x" "$(DESTDIR)$(PREFIX)/bin/$$x"; fi; \
+	done
+	if [ -f "utility/w90pov/w90pov" ]; then install -m755 "utility/w90pov/w90pov" "$(DESTDIR)$(PREFIX)/bin/w90pov"; fi;
+	if [ -f "utility/w90vdw/w90vdw.x" ]; then install -m755 "utility/w90vdw/w90vdw.x" "$(DESTDIR)$(PREFIX)/bin/w90vdw.x"; fi;
+	install -d $(DESTDIR)$(PREFIX)/lib/
+	if [ -f "libwannier.a" ]; then install -m644 "libwannier.a" "$(DESTDIR)$(PREFIX)/lib/libwannier.a"; fi;
+
 all: wannier lib post w90chk2chk w90pov w90vdw w90spn2spn
 
 doc: thedoc
@@ -205,4 +217,4 @@ objdirp:
 		then mkdir src/objp ; \
 	fi ) ;
 
-.PHONY: wannier default all doc lib libs post clean veryclean thedoc dist test-serial test-parallel dist-lite objdir objdirp serialobjs tests w90spn2spn
+.PHONY: wannier default all doc lib libs post clean veryclean thedoc dist test-serial test-parallel dist-lite objdir objdirp serialobjs tests w90spn2spn install

README.install

@@ -48,6 +48,7 @@
                    the user guide)
    make w90vdw     build the van der Waals code
    make w90pov     build the ray-tracing code
+   make install    install the built binaries
    make tests      run test cases
    make doc        build the documentation
    make dist       make a tar-ball of the distribution
@@ -58,6 +59,11 @@
  'make -j NN' will allow compilation using NN multiple threads.
  On a multicore CPU this will build the executables in a shorter time.
 
+ 'make install' supports DESTDIR and PREFIX variables.
+ Executables will be installed into $(DESTDIR)$(PREFIX)/bin directory,
+ libraries will be installed into $(DESTDIR)$(PREFIX)/lib directory.
+ The default DESTDIR is empty, and the default PREFIX is /usr.
+
  In order to compile the postw90.x executable in its parallel version, you have
  to specify 
   COMMS=mpi
@@ -78,7 +84,7 @@
   LAPACK can be obtained from the netlib website. It also includes a 
   non-optimised BLAS.
      http://www.netlib.org/lapack/
-     
+
 
 Linux x86,x86-64
 ----------------

README.rst

@@ -35,9 +35,9 @@ this code:
   L. Paulatto, S. Poncé, T. Ponweiser, J. Qiao, F. Thöle, S.S. Tsirkin, 
   M. Wierzbowska, N. Marzari, D. Vanderbilt, I. Souza, A.A. Mostofi, J.R. Yates, 
   Wannier90 as a community code: new features and applications, 
-  `arXiv:1907.09788`_ (2019)
+  `J. Phys. Cond. Matt. 32, 165902`_ (2020)
 
-.. _arXiv:1907.09788: https://arxiv.org/abs/1907.09788
+.. _J. Phys. Cond. Matt. 32, 165902: https://doi.org/10.1088/1361-648X/ab51ff
 
 If you are using versions 2.x of the code, cite instead:
 
@@ -46,7 +46,7 @@ If you are using versions 2.x of the code, cite instead:
   obtaining maximally-localised Wannier functions*, 
   `Comput. Phys. Commun. 185, 2309 (2014)`_ 
 
-.. _Comput. Phys. Commun. 185, 2309 (2014): http://dx.doi.org/10.1016/j.cpc.2014.05.003
+.. _Comput. Phys. Commun. 185, 2309 (2014): http://doi.org/10.1016/j.cpc.2014.05.003
 
 For the method please cite:
 

doc/tutorial/tutorial.tex

@@ -6,6 +6,7 @@
 \usepackage{amsmath}
 \usepackage{graphicx}
 \usepackage{fancyhdr}
+\usepackage{subfig}
 \usepackage[T1]{fontenc} % important for having searchable underscores
 \usepackage{bm}% bold math
 \usepackage[sort&compress,numbers]{natbib}
@@ -23,6 +24,8 @@
 %\let\oldundercore=\_
 %\def\_{\oldunderscore}
 
+\usepackage{textcomp}
+
 % set fancy headings
 
 \pagestyle{fancy}
@@ -2905,7 +2908,7 @@ \subsection*{Shift current $\sigma^{abc}$}
 \begin{itemize}
   \item[1]{Valence bands: In this case we will compute 4 localized WFs corresponding to the 4 valence bands of Silicon. These 4 bands constitute a manifold that is separated in energy from other bands. In this case the columns of the density matrix are already localized in real space and no extra parameter is required.}
   \begin{enumerate}
-    \item Copy the input files {\tt si.scf, si\_4bands.nscf} and {\tt si.pw2wan} from the {\tt input\_files directory} into the {\tt isolated} folder
+    \item Copy the input files {\tt si.scf} and {\tt si\_4bands.nscf} from the {\tt input\_files} directory into the {\tt isolated} folder
     \item Run \pwscf\ to obtain the ground state charge of bulk Silicon. \\
     {\tt pw.x < si.scf > scf.out}
 
@@ -2932,7 +2935,7 @@ \subsection*{Shift current $\sigma^{abc}$}
   \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
+    \item Copy the input files {\tt si.scf} and {\tt si\_12bands.nscf} from the {\tt input\_files} folder into the {\tt erfc} folder
     \item Run \pwscf\ to obtain the ground state charge of bulk Silicon. \\
     {\tt pw.x < si.scf > scf.out}
 
@@ -2957,7 +2960,7 @@ \subsection*{Shift current $\sigma^{abc}$}
   \end{enumerate}
   \item[3]{Conduction bands only: In this case we will compute 4 localized WFs corresponding to the 4 low-lying conduction bands only. As for the previous point, we need to define a modified density matrix\cite{LinLin-ArXiv2017}. Since we are only interested in a subset of the conduction states, within a bounded energy region, a good choice for $f(\varepsilon_{n,\mathbf{k}})$ is: $$f(\varepsilon_{n,\mathbf{k}}) = \exp\left(-\frac{(\varepsilon_{n,\mathbf{k}} - \mu)^2}{\sigma^2}\right).$$}
     \begin{enumerate}
-    \item Copy the input files {\tt si.scf, si\_12bands.nscf} and {\tt si.pw2wan} from the {\tt input\_files directory} into the {\tt gaussian} folder
+    \item Copy the input files {\tt si.scf} and {\tt si\_12bands.nscf} from the {\tt input\_files} directory into the {\tt gaussian} folder
     \item Run \pwscf\ to obtain the ground state charge of bulk Silicon. \\
     {\tt pw.x < si.scf > scf.out}
 
@@ -3581,6 +3584,93 @@ \subsection*{Notes}
 
 \end{enumerate}
 
+\sectiontitle{32: Tungsten --- SCDM parameters from projectability}
+
+\begin{itemize}
+        \item{Outline: {\it Compute the Wannier interpolated band structure of tungsten (W)
+                            using the SCDM method to calculate the initial guess (see Example 27 for more details). The free parameters
+                            in the SCDM method, i.e., $\mu$ and $\sigma$, are obtained by fitting 
+                            a complementary error
+                            function to the projectabilities. The number of MLWFs is given by the number
+                            of pseudo-atomic orbitals (PAOs) in the pseudopotential, $21$ in this case. All the steps shown in this example have been automated in the AiiDA\cite{Pizzi_AiiDA} workflow that can be downloaded from the MaterialsCloud website\cite{MaterialsCloudArchiveEntry}}.}
+        \item{Directory: {\tt examples/example31/}}
+        \item{Input files}
+        \begin{itemize}
+                \item{ {\tt W.scf} {\it The \pwscf\ input file for ground state
+                                calculation}}
+                \item{ {\tt W.nscf}  {\it The \pwscf\ input file to obtain Bloch
+                                states on a uniform grid}}
+                \item{ {\tt W.pw2wan}  {\it The input file for {\tt pw2wannier90}}}
+                \item{ {\tt W.proj}  {\it The input file for {\tt projwfc}}}
+                \item{ {\tt generate\_weights.sh} {\it The bash script to extract the projectabilities from the output of {\tt projwfc} }}
+                \item{ {\tt W.win}  {\it The {\tt wannier90} input file}}
+        \end{itemize}
+\end{itemize}
+
+\begin{enumerate}
+	\item Run \pwscf\ to obtain the ground state of tungsten\\
+	{\tt pw.x -in W.scf > scf.out}
+
+	\item Run \pwscf\ to obtain the Bloch states on a $10\times10\times10$ uniform $k$-point
+	grid\\ 
+	{\tt pw.x -in W.nscf > nscf.out}
+
+	\item Run \wannier\ to generate a list of the required overlaps (written
+	into the {\tt W.nnkp} file)\\
+	{\tt wannier90.x -pp W}
+
+        \item Run {\tt projwfc} to compute the projectabilities of the Bloch states
+              onto the Bloch sums obtained from the PAOs in the pseudopotential \\
+        {\tt projwfc.x -in W.proj > proj.out}
+
+        \item Run {\tt generate\_weights} to extract the projectabilitites from {\tt proj.out}
+              in a format suitable to be read by Xmgrace or gnuplot \\
+	{\tt ./generate\_weights.sh}
+
+        \item Plot the projectabilities and fit the data with the complementary error function
+              $$f(\epsilon;\mu,\sigma) = \frac{1}{2}\mathrm{erfc}(-\frac{\mu - \epsilon}{\sigma}).$$
+		We are going Xmgrace to plot the projectabilities and perform the fitting. Open Xmgrace \\
+	{\tt xmgrace }
+
+	To Import the {\tt p\_vs\_e.dat} file, click on {\tt Data} from the top bar and then {\tt Import -> ASCII...}.
+	At this point a new window {\tt Grace: Read sets} should pop up. Select {\tt p\_vs\_e.dat} in the {\tt Files} section, click {\tt Ok} at the bottom and close the window. You should now be able to see a quite noisy function that is bounded between 1 and 0. You can modify the appearence of the plot by clicking on {\tt Plot} in the top bar and then {\tt Set appearance...}. In the {\tt Main} section of the pop-up window change the symbol type from {\tt None} to {\tt Circle}. Change the line type from straight to none, since the lines added by default by Xmgrace are not meaningful. For the fitting, go to {\tt Data -> Transformations -> Non-linear curve fitting}. In this window, select the source from the {\tt Set} box and in the {\tt Formula} box insert the following \\
+
+	{\tt y = 0.5 * erfc( ( x - A0 ) / A1 )}  \\
+
+Select 2 as number of parameters, give 40 as initial condition for {\tt A0} and 7 for {\tt A1}. Click {\tt Apply}. A new window should pop up with the stats of the fitting. In particular you should find a {\tt Correlation coefficient} of 0.96 and a value of $39.9756$ for {\tt A0} and $6.6529$ for {\tt A1}. These are the value of $\mu_{fit}$ and $\sigma_{fit}$ we are going to use for the SCDM method. In particular, $\mu_{SCDM} = \mu_{fit} - 3\sigma_{fit} = 20.0169$ eV and $\sigma_{SCDM} = \sigma_{fit} = 6.6529$ eV. The motivation for this specific choice of $\mu_{fit}$ and $\sigma_{fit}$ may be found in Ref.~\cite{Vitale2019automated}, where the authors also show validation of this approach on a dataset of 200 materials. You should now see the fitting function, as well as the projectabilities, in the graph (see Fig. \ref{fig:W_fit}-(a)).\\
+
+        \item Open {\tt W.pw2wan} and append the following lines
+	{\tt 
+
+	scdm\_entanglement = \textquotesingle erfc\textquotesingle
+
+  	scdm\_mu =  20.0169
+
+  	scdm\_proj = .true.
+
+  	scdm\_sigma =   6.6529
+
+ 	/}
+
+	\item Run {\tt pw2wannier90} to compute the overlaps between Bloch
+	states and the projections for the starting guess (written in the
+	{\tt W.mmn} and {\tt  W.amn} files)\\
+	{\tt pw2wannier90.x -in W.pw2wan > pw2wan.out}
+
+	\item Run \wannier\ to obtain the interpolated bandstructure (see Fig. \ref{fig:W_fit}-(b)).\\
+	{\tt wannier90.x W}
+
+Please cite Ref.~\cite{Vitale2019automated} in any publication employing the procedure outlined in this example to obtain $\mu$ and $\sigma$.
+\end{enumerate}
+
+\begin{figure}
+\centering
+\subfloat[]{\includegraphics[width=0.45\columnwidth]{./W_fit.png}}
+\subfloat[]{\includegraphics[width=0.45\columnwidth]{./W_bs.pdf}}
+\caption{ a) Each blue dot represents the projectability as defined in Eq. (22) of Ref. \cite{Vitale2019automated}  of the state
+$\vert n\mathbf{k} \rangle$ as a function of the corresponding energy $\epsilon_{n\mathbf{k}}$ for tungsten. The yellow line shows the fitted complementary error function. The vertical red line represents the value of $\sigma_{fit}$ while the vertical green line represents the optimal value of $\mu_{SCDM}$, i.e. $\mu_{SCDM} = \mu_{fit} - 3\sigma_{fit}$. b) Band structure of tungsten on the $\Gamma$-H-N-$\Gamma$ path from DFT calculations (solid black) and Wannier interpolation using the SCDM method to construct the initial guess (red dots).}
+\label{fig:W_fit}
+\end{figure}
 
 %\cleardoublepage
 

doc/user_guide/faq.tex

@@ -91,8 +91,8 @@ \subsection{I like \wannier! Should I donate anything to its authors?}
    F. Th\"ole, S.S. Tsirkin, M. Wierzbowska, N. Marzari, D. Vanderbilt, 
    I. Souza, A.A. Mostofi, J.R. Yates,\\
    Wannier90 as a community code: new features and 
-  applications, \emph{arXiv:1907.09788} (2019)\\
-  \url{https://arxiv.org/abs/1907.09788}
+  applications, \emph{J. Phys. Cond. Matt.} {\bf 32}, 165902 (2020)\\
+  \url{https://doi.org/10.1088/1361-648X/ab51ff}
 \end{quote}
 
 If you are using versions 2.x of the code, cite instead:
@@ -103,7 +103,7 @@ \subsection{I like \wannier! Should I donate anything to its authors?}
 An updated version of \wannier: 
 A Tool for Obtaining Maximally-Localised Wannier
   Functions, {\it Comput. Phys. Commun.} {\bf 185}, 2309 (2014)\\
-\url{http://dx.doi.org/10.1016/j.cpc.2014.05.003}
+\url{http://doi.org/10.1016/j.cpc.2014.05.003}
 \end{quote} 
 
 \section{Installation}

doc/user_guide/files.tex

@@ -693,6 +693,73 @@ \section{{\tt seedname\_r.dat}}
 and $n$, and the real and imaginary parts of the position matrix element
 in the WF basis.
 
+\section{{\tt seedname\_tb.dat}}
+
+OUTPUT. Written if {\tt write\_tb=.TRUE.}. This file is essentially a 
+combination of {\tt seedname\_hr.dat} 
+and {\tt seedname\_r.dat}, plus lattice vectors. 
+The first line gives the date and
+time at which the file was created. 
+The second to fourth lines are the lattice vectors in Angstrom unit. 
+
+\begin{verbatim}
+ written on 27Jan2020 at 18:08:42 
+  -1.8050234585004898        0.0000000000000000        1.8050234585004898     
+   0.0000000000000000        1.8050234585004898        1.8050234585004898     
+  -1.8050234585004898        1.8050234585004898        0.0000000000000000 
+\end{verbatim}
+
+The next part is the same as {\tt seedname\_hr.dat}. 
+The fifth line states the number of Wannier functions {\tt num\_wann}. 
+The sixth line gives the number of Wigner-Seitz grid-points {\tt nrpts}. 
+The next block of {\tt nrpts} integers gives the degeneracy of 
+each Wigner-Seitz grid point, with 15 entries per line.
+Then, the next {\tt num\_wann}$^2 \times$ {\tt nrpts} lines
+each contain, respectively, the components of the vector $\mathbf{R}$
+in terms of the lattice vectors $\{\mathbf{A}_{i}\}$, the indices $m$
+and $n$, and the real and imaginary parts of the Hamiltonian matrix element
+$H_{mn}^{(\mathbf{R})}$ in the WF basis, e.g.,
+
+\begin{verbatim}    
+           7
+          93
+    4    6    2    2    2    1    2    2    1    1    2    6    2    2    2
+    6    2    2    4    1    1    1    4    1    1    1    1    2    1    1
+    1    2    2    1    1    2    4    2    1    2    1    1    1    1    2
+    1    1    1    2    1    1    1    1    2    1    2    4    2    1    1
+    2    2    1    1    1    2    1    1    1    1    4    1    1    1    4
+    2    2    6    2    2    2    6    2    1    1    2    2    1    2    2
+    2    6    4
+
+   -3    1    1
+    1    1    0.42351556E-02 -0.95722060E-07
+    2    1    0.69481480E-07 -0.20318638E-06
+    3    1    0.10966508E-06 -0.13983284E-06
+    .
+    .
+    .
+\end{verbatim}
+
+Finally, the last part is the same as {\tt seedname\_r.dat}. 
+The {\tt num\_wann}$^2 \times$ {\tt nrpts} lines
+each contain, respectively, the components of the vector $\mathbf{R}$
+in terms of the lattice vectors $\{\mathbf{A}_{i}\}$, the indices $m$
+and $n$, and the real and imaginary parts of the position matrix element
+in the WF basis (the float numbers in columns 3 and 4 are the 
+real and imaginary parts for $\langle m\mathbf{0}|\mathbf{r}_x|n\mathbf{R}\rangle$,
+columns 5 and 6 for $\langle m\mathbf{0}|\mathbf{r}_y|n\mathbf{R}\rangle$, 
+and columns 7 and 8 for $\langle m\mathbf{0}|\mathbf{r}_z|n\mathbf{R}\rangle$), e.g.
+
+\begin{verbatim}
+   -3    1    1
+    1    1    0.32277552E-09  0.21174901E-08 -0.85436987E-09  0.26851510E-08  ...
+    2    1   -0.18881883E-08  0.21786973E-08  0.31123076E-03  0.39228431E-08  ...
+    3    1    0.31123242E-03 -0.35322230E-09  0.70867281E-09  0.10433480E-09  ...
+    .
+    .
+    .
+\end{verbatim}
+
 \section{{\tt seedname.bvec}}
 OUTPUT.
 Written if $\verb#write_bvec#=\verb#true#$. This file contains 

doc/user_guide/overview.tex

@@ -33,8 +33,8 @@ \section*{Citation}
   F. Th\"ole, S.S. Tsirkin, M. Wierzbowska, N. Marzari, D. Vanderbilt, 
   I. Souza, A.A. Mostofi, J.R. Yates,\\
   Wannier90 as a community code: new features and 
-    applications, \emph{arXiv:1907.09788} (2019)\\
-    \url{https://arxiv.org/abs/1907.09788}
+    applications, \emph{J. Phys. Cond. Matt.} {\bf 32}, 165902 (2020)\\
+    \url{https://doi.org/10.1088/1361-648X/ab51ff}
   \end{quote}
 
 If you are using versions 2.x of the code, cite instead:  
@@ -133,7 +133,7 @@ \section*{Credits}
 and David Vanderbilt and for entangled bands by Ivo Souza, Nicola Marzari,
 and David Vanderbilt.
 
-\wannier\ \copyright\ 2007-2019 The Wannier Developer Group and individual contributors
+\wannier\ \copyright\ 2007-2020 The Wannier Developer Group and individual contributors
 
 \section*{Licence}
 All the material in this distribution is free software; you can