Developing the nerwann module to calculate thermomagnetic coefficients

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### New features
 
+- Calculation of the isothermal Nernst, isothermal Hall, and ettingshausen coefficients explained in malism given in S.Emad Rezaei, Mona Zebarjadi,and Keivan Esfarjani, COMMAT_111412, 214402 (2022) + examples 34
+- 
 - Calculation of spin Hall conductivity according to the formalism given in Junfeng Qiao, Jiaqi Zhou, Zhe Yuan and Weisheng Zhao, PRB 98, 214402 (2018) + examples 29 and 30 and tests [[#264]](https://github.com/wannier-developers/wannier90/pull/264)
 
 - Implementation of the SCDM method in Wannier90 for spinor wavefunctions and added example31 for the tutorial [[#277]](https://github.com/wannier-developers/wannier90/pull/277)

doc/tutorial/tutorial.tex

@@ -3795,7 +3795,62 @@ \subsection*{Expansion coefficients}
 
 \end{itemize}
 
+\sectiontitle{34: InSb -- Nernst effect}
+\begin{itemize}
+\item{Outline: \it{Achieve MLWFs for the valence and low-lying
+    conduction bands of InSb. Compute the isothermal Nernst, isothermal Hall, and Ettingshausen coefficients  within the relaxation time approximation the \nw\ module.}} 
+\end{itemize}
+\begin{itemize}
+  \item{Directory: {\tt examples/example34}}
+  \item{Input Files}
+    \begin{itemize}
+      \item{ {\tt InSb.scf}  {\it The \pwscf\ input file for ground state
+	  calculation}}
+      \item{ {\tt InSb.nscf}  {\it The \pwscf\ input file to achieve Bloch
+	  states for the conduction states}} 
+      \item{ {\tt InSb.pw2wan}  {\it Input file for {\tt pw2wannier90}}}
+      \item{ {\tt InSb.win}  {\it The {\tt wannier90} input file}}
+    \end{itemize}
+\end{itemize}
+
+
+\begin{enumerate}
+\item Run \pwscf\ to achieve the ground bands of InSb\\  
+{\tt pw.x < InSb.scf > scf.out}
+
+\item Run \pwscf\ to achieve the Bloch states on a uniform k-point
+  grid.\\ 
+{\tt pw.x < InSb.nscf > nscf.out}
+
+\item Run \wannier\ to generate a list of the required overlaps (written
+  into the {\tt InSb.nnkp} file).\\
+{\tt wannier90.x -pp InSb}
+
+\item Run {\tt pw2wannier90} to obtain the overlap between Bloch
+  states and the projections for the starting guess (written in the
+  {\tt InSb.mmn} and {\tt  InSb.amn} files).\\
+{\tt pw2wannier90.x < InSb.pw2wan > pw2wan.out}
+
+\item Run \wannier\ to compute the MLWFs.\\
+{\tt wannier90.x InSb}
+
+
+\item Run \postw\ to calculate thermomagnetic responses.\\
+{\tt postw90.x InSb} (serial execution) \\
+{\tt mpirun -np 8 postw90.x InSb} (parallel execution) 
+\end{enumerate}
 
+The output file {\tt InSb.wpout} shows the details of the calculation. Ensure that there are no errors and no unwanted flags are passed to \nw . The first order ({\tt InSb\_tdf1.dat}) and second order ({\tt InSb\_tdf2.dat}) transport distribution functions are saved in two files. You will need to download the post processing "NERTAW.py" code form the GitHub page of the author (Emad-Rezaei) to calculate the isothermal Hall conductivity, isothermal Nernst coefficient, and Ettingshausen coefficient. The detailed information is available in the documentation of the "NERTAW" code. 
+Please keep in mind that this is only a representative example and the results have to converge with respect to interpolation mesh which often requires a reasonably fine mesh.  
+
+\subsection*{Further ideas}
+
+\begin{itemize}
+\item Change the interpolation to a $60\times 60\times 60$ mesh and run again \postw\ to check if the results for thermomagnetic responses converge. Please note that it might take long depending on your machine.  
+
+\item You might want to plot the Nernst coefficient versus carrier concentration, also change the temperature and see how the Nernst coefficient behaves.
+
+\end{itemize}
 %\cleardoublepage
 
 \bibliographystyle{apsrev4-1}

doc/user_guide/nerwann.tex

@@ -0,0 +1,101 @@
+%!TEX root=./user_guide.tex
+\chapter{Thermomagnetic calculations with the \bw\ module} \textbf{nerwann}. 
+
+The flag $\verb#nerwann#=\verb#TRUE#$ will prompt the computation of the isothermal Nernst, isothermal Hall, and Ettingshausen coefficients by solving the Boltzmann transport equation in the presence of a magnetic field within the constant time relaxation approximation. Each quantity is defined in the following section\ref{nerwann-theory} 
+
+The parameters of the nerwann module are described in the documentation as well as an example of computing thermomagnetic properties of GaAs in the Tutorial. 
+
+Thermomagnetic responses largely depend on the magnitude of magnetic field which needs to be specified by the user via the \textbf{bext} flag in the input file.
+
+
+citing the following paper would be greatly appreciated when publishing data attained using the nerwann module:
+\begin{quote}
+S.E. Rezaei, M. Zebarjadi, and K. Esfarjani, \\
+\emph{Calculation of thermomagnetic properties using first-principles density functional theory}, Comput. Mater. Sci. 210, 111412 (2022), DOI:10.1016/j.commatsci.2022.111412.
+\end{quote}
+
+%Reference: [Comput. Mater. Sci paper]
+\section{Theory}
+\label{nerwann-theory}
+In response to external fields, at a point $k$ in the reciprocal space, the distribution function $f_{k}$ deviates from the equilibrium distribution function $f_{k}^{0}$ as $f_{k}\textbf{=}f_{k}^{0}+f_{k}^{1}$. Moreover, the presence of a magnetic field causes a force acting on a particle described by Lorentz force $q\nu\times H$, and subsequently, the BTE will be modified as follows~\cite{smith1967electronic}: 
+\begin{equation}
+\frac{q}{\hbar}\nu\times H\cdot \nabla _{k} f_{k}^{1}+\nu \cdot [q\varepsilon + T\nabla (\frac{E_{k}-\mu}{T})]\frac{\partial f_{k}^{0}}{\partial E_{k}}\textbf{=}- \frac{f_{k}^{1}}{\tau}
+\label{eq1}   
+\end{equation}
+Where q is the electron charge, $\hbar$ is the Planck constant, T is the temperature, $\varepsilon$ is the electric field, $E_{k}$ is the band energy and $\mu$ is the chemical potential. Eq.~\ref{eq1} can be abbreviated by introducing a generalized force, $F$, and a band operator, $\Omega$ defined as follows:
+\begin{equation}
+\begin{split}
+%&F\textbf{=}-\nabla \mu +(E_{k}-\mu)T\nabla (\frac{1}{T}) \\
+&F\textbf{=}-\nabla \mu -\frac{(E_{k}-\mu)}{T}\nabla T) \\
+&\Omega\textbf{=}\frac{q}{\hbar}\nu\times H\cdot\nabla _{k}\textbf{=}\frac{q}{\hbar}\nu _{j}H_{k}\epsilon _{ijk}(\frac{\partial}{\partial k_{i}}) 
+\end{split}
+\label{eq2}
+\end{equation}
+Inserting ~\ref{eq2} in ~\ref{eq1} results in an equation for $f_{k}^{1}$:
+\begin{equation}
+f_{k}^{1}\textbf{=}(1+\tau \Omega)^{-1}\tau \nu \cdot F(-\frac{\partial f_{k}^{0}}{\partial E_{k}})
+\label{eq3}
+\end{equation}
+When  $\tau \Omega$ is small, at small magnetic fields, the term $(1+\tau \Omega)^{-1}$ can be expanded according to the Jones-Zener expansion~\cite{jones-zener}:
+\begin{equation}
+(1+\tau \Omega)^{-1}\textbf{=}1-\tau \Omega +(\tau \Omega)^{2}-\dots
+\label{eq4}
+\end{equation}
+For the Nernst effect the first two terms (1-$\tau \Omega$) are needed to achieve a response linear in $H$, and higher order terms are neglected, thus, the transport distribution function (Eq.~\ref{eq3}) is modified as:
+\begin{equation}
+f_{k}^{1}\textbf{=}-F_{i}\frac{\partial f_{k}^{0}}{\partial E_{k}}\tau [1-\tau \Omega]\nu _{j}
+\label{eq5}
+\end{equation}
+The physical constants (G) and transport coefficients($(ij)_{H}$) are defined as comprehensive tensors. 
+\begin{equation}
+    \begin{split}
+    G\textbf{=}\begin{pmatrix}
+q^2 \\
+\frac{q}{T}(E-\mu) \\
+q(E-\mu) \\
+\frac{(E-\mu)^2}{T} \\
+\end{pmatrix} \\
+(ij)_{H}\textbf{=}\begin{pmatrix}
+\sigma_{ij}(H) \\
+B_{ij}(H) \\
+\rho _{ij}(H) \\
+\kappa _{ij} (H) \\
+\end{pmatrix} 
+\label{eqmtrx}
+    \end{split}
+\end{equation}
+The transport distribution function ($\Xi ^H$) for thermomagnetic effect relates the $(ij)_H$ and G tensors as below~\cite{rezaei2022crta,rezaei2023rta}:
+\begin{equation}
+ %\fontsize{8}{11}\selectfont
+    \begin{split}
+        &(ij)_H\textbf{=}\int G \, \Xi_{ij}^H (E)\left(-\frac{\partial f(E,\mu,T)}{\partial E}\right) dE \\
+     &\Xi_{ij}^H(E)\textbf{=}\frac{1}{VN_k}\sum_{n,k}\nu_{i,nk}\tau_{nk}[\nu_{j,nk}-\Omega\,\tau_{nk}\,\nu_{j,nk}]\,\delta(E-E_{k})
+        \label{eq6}
+    \end{split}
+\end{equation}
+Table.~\ref{TMco} summarizes the definition of each thermomagnetic response function along with their corresponding boundary conditions.
+\begin{table}
+ \caption{Isothermal Nernst (N$_{T}$), Isothermal Hall (H$_{T}$), and Ettinghausen ($\eta$) coefficients in Adiabatic (A) and Isothermal (T) conditions. $\alpha$,$\rho$,$\kappa$, and $\pi$ are the Seebeck coefficient, electrical resistivity, thermal conductivity and Peltier coefficient, respectively.}
+ \centering
+ \noindent
+ \begin{tabular}{lccc} %crrrr}
+    \hline
+    \hline
+    \textbf{Coefficient} &\textbf{Measure} &\textbf{Boundary Conditions} & \textbf{Equation}  \\
+    \hline
+    \hline
+   $N_{T}$  & $\frac{\varepsilon_y}{\partial_x T}$ & J=0, $ \partial_yT\textbf{=}0$ & $\alpha_{yx}(H)$   \\
+    $H_{T}$  & $\frac{\varepsilon_y}{J_x }$ &  J=J$_x, \nabla T\textbf{=}0$ & $\rho _{yx}(H)$ \\
+    $\eta$    & $\frac{\partial_yT}{J_x}$ &  J=J$_x$, $Q_y\textbf{=}0$ $\partial_xT\textbf{=}0$ & $\frac{\pi_{yx}(H)}{\kappa_{yy}(H)}$\\
+    \hline  
+    \hline 
+ \end{tabular}
+ \label{TMco}
+\end{table}
+
+\section{Files}
+
+\subsection{{\tt seedname\_tdf1.dat}}
+OUTPUT. This file contains the first term of Transport Distribution Function ($\Xi_{ij}^H(E)$~\ref{eq6}) with no relaxation time as $\frac{1}{VN_k}\sum_{n,k}\nu_{i,nk}\nu_{j,nk}\delta(E-E_{k})$. The first few lines are descriptions that are commented. The first column is energy in eV unit, followed by nine components of the first order Transport Distribution Function. When spin decomposition is needed, 12  more columns will be added for spin up and down contributions.  It is noteworthy to add that the 1st order Transport Distribution Function is printed out in the SI units of  $1/kg.m^3$.   
+\subsection{{\tt seedname\_tdf2.dat}}
+OUTPUT. This file contains the second term of Transport Distribution Function ($\Xi_{ij}^H(E)$~\ref{eq6}) with no relaxation time as $\frac{1}{VN_k}\sum_{n,k}\nu_{i,nk}\Omega\,\nu_{j,nk}\,\delta(E-E_{k})$. The first few lines are descriptions that are commented. The first column is energy in eV unit, followed by nine components of the second order Transport Distribution Function. When spin decomposition is needed, 12  more columns will be added for spin up and down contributions.  The 2nd order Transport Distribution Function is saved in the SI units of  $1/s.kg.m^3$. 

doc/user_guide/postw90params.tex

@@ -102,6 +102,8 @@ \section{List of available modules}
   properties for bulk materials using the semiclassical Boltzmann
   transport equation (see Chap.~\ref{ch:boltzwann} and example 16 of
   the tutorial).
+  \item \texttt{NerWann}: Calculation of thermomagnetic properties for bulk materials using the semiclassical Boltzmann transport equation in the presence of a magnetic field (see Chap.~\ref{ch:nerwann} and example 33 of
+  the tutorial).
 \item \texttt{geninterp} (Generic Band Interpolation): Calculation band energies (and band
   derivatives) on a generic list of $k$ points (see Chap.~\ref{ch:geninterp}).
 \end{itemize}
@@ -263,10 +265,10 @@ \section{Keyword List}
 
 
 
-\begin{longtable}{|c|c|p{6cm}|}
-%\begin{table}[h!]
-%\begin{center}
-%\begin{tabular}{|c|c|p{6cm}|}
+%\begin{longtable}{|c|c|p{6cm}|}
+\begin{table}[h!]
+\begin{center}
+\begin{tabular}{|c|c|p{6cm}|}
   \hline
   Keyword & Type & Description \\
   &      &             \\
@@ -315,16 +317,16 @@ \section{Keyword List}
   {\sc kdotp\_num\_bands} & I & Number of bands for $k\cdot p$ expansion \\
   {\sc kdotp\_bands} & I & Band indexes corresponding to the $k\cdot p$ bands \\
   \hline
-%\end{tabular}
+\end{tabular}
 \caption[Parameter file keywords controlling the Berry module.]  {{\tt
     seedname.win} file keywords controlling the {\tt berry}
   module. Argument types are represented by, I for a integer, R for a
   real number, P for a physical value, L for a logical value and S for
   a text string.}
 \label{parameter_keywords_berry}
-%\end{center}
-%\end{table}
-\end{longtable}
+\end{center}
+\end{table}
+%\end{longtable}
 
 
 \begin{table}[h!]
@@ -419,6 +421,37 @@ \section{Keyword List}
 \end{center}
 \end{table}
 
+%nerwann table
+\begin{table}[h!]
+\begin{center}
+\begin{tabular}{|c|c|p{6cm}|}
+\hline
+Keyword & Type & Description \\
+        &      &             \\
+\hline\hline
+\multicolumn{3}{|c|}{{\tt NerWann} Parameters} \\
+\hline
+{\sc nerwann}   & L & Calculate thermomagnetic properties \\
+{\sc [ner\_]kmesh} & I & Dimensions of the uniform interpolation 
+$k$-mesh (one or three integers)\\ 
+{\sc [ner\_]kmesh\_spacing} & R & Minimum distance between $k$ points in \AA$^{-1}$\\
+{\sc ner\_tdf\_energy\_step} & R & Energy step size for the total transport distribution (eV) \\
+{\sc ner\_tdf\_smr\_type} & S & Smearing type for the total transport distribution \\
+{\sc ner\_tdf\_smr\_fixed\_en\_width} & P & Smearing for the total transport distribution (eV) \\
+{\sc ner\_bandshift} & L & shift of the conduction bands\\
+{\sc ner\_bandshift\_firstband} & I & Index of the first band to be shifted\\
+{\sc ner\_bandshift\_energyshift} & P & Energy shift of the conduction bands in eV\\
+{\sc ner\_bext} & R & External magnetic field in T\\
+\hline
+\end{tabular}
+\caption[Parameter file keywords controlling the \nw\ module.]
+{{\tt seedname.win} file keywords controlling the \nw\ module (calculation of thermomagnetic properties in the Wannier basis). Argument types
+are represented by, I for a integer, R for a real number, P for a
+physical value, L for a logical value and S for a text string.}
+\label{parameter_keywords_bw}
+\end{center}
+\end{table}
+
 \begin{table}[h!]
 \begin{center}
 \begin{tabular}{|c|c|p{6cm}|}
@@ -573,9 +606,9 @@ \section{Global variables}
 \subsection[spin\_decomp]{\tt logical :: spin\_decomp}
 If {\tt true}, extra columns are added to some output files (such as
 {\tt seedname-dos.dat} for the {\tt dos} module, and analogously for
-the {\tt berry} and {\tt BoltzWann} modules).
+the {\tt berry}, {\tt BoltzWann} modules, and {\tt NerWann} modules).
 
-For the {\tt dos} and {\tt BoltzWann} modules, two further columns are
+For the {\tt dos}, {\tt BoltzWann}, and {\tt NerWann} modules, two further columns are
 generated, which contain the decomposition of the required property
 (e.g., total or orbital-projected DOS) of a spinor calculation into
 up-spin and down-spin parts (relative to the quantization axis defined
@@ -1749,7 +1782,54 @@ \section{BoltzWann}
 The units are eV.
 No default value; if {\tt boltz\_bandshift} is \verb#true#, this flag must be provided.
 
+\clearpage
+\section{NerWann}
+\subsection[nerwann]{\tt logical :: nerwann}
+Determines whether to compute the isothermal Hall conductivity, isothermal Nernst coefficient , and Ettingshausen coefficient.
 
+The default value is \verb#false#.
+
+\subsection[ner\_kmesh]{\tt integer :: ner\_kmesh(:)}
+It specifies the interpolation $k$ mesh used to calculate the total transport distribution function. 
+
+\subsection[ner\_kmesh\_spacing]{\tt real(kind=dp) :: ner\_kmesh\_spacing}
+Overrides the \verb#kmesh_spacing# global variable (see
+Sec.~\ref{sec:postw90-globalflags}).
+
+\subsection[ner\_tdf\_energy\_step]{\tt real(kind=dp) :: ner\_tdf\_energy\_step}
+Energy step for the grid of energies in the total transport distribution function.
+
+The units are eV and the default value is 0.001~eV.
+
+\subsection[ner\_tdf\_smr\_type]{\tt character(len=120) :: ner\_tdf\_smr\_type}
+The type of smearing function to be used for the total transport distribution function. The default value is the one given via the {\tt smr\_type} input flag (if defined).
+
+\subsection[ner\_tdf\_smr\_fixed\_en\_width]{\tt real(kind=dp) :: ner\_tdf\_smr\_fixed\_en\_width}
+Energy width for the smearing function in eV unit. For the total transport distribution function, a standard (non-adaptive) smearing scheme is used.
+
+The default value is 0~eV. Note that if the width is smaller than twice the energy step {\tt ner\_tdf\_energy\_step}, the total transport distribution function will be unsmeared.
+
+
+\subsection[ner\_bandshift]{\tt logical :: ner\_bandshift}
+Shift all conduction bands by the value of  {\tt ner\_bandshift\_energyshift}. Such a shift is applied after interpolation and the index of the first band to shift is required. 
+
+
+The default value is \verb#false#.
+
+\subsection[ner\_bandshift\_firstband]{\tt integer :: ner\_bandshift\_firstband}
+Index of the first conduction band to shift.
+
+It means that this band and all the above bands all bands will be shifted by  {\tt ner\_bandshift\_energyshift}. This 
+
+The units are eV and it has to be specified if {\tt ner\_bandshift} is \verb#true#. 
+
+\subsection[ner\_bandshift\_energyshift]{\tt real(kind=dp) :: ner\_bandshift\_energyshift}
+Energy shift of the conduction bands in the unit of eV. It has to be provided if {\tt ner\_bandshift} is \verb#true#.
+
+\subsection[ner\_bext]{\tt real(kind=dp) :: bext(3)}
+The external magnetic field vector in units of Tesla for the calculation of thermomagnetic properties. The default value is (0.0,0.0,0.0)
+
+\clearpage
 \section{Generic Band Interpolation}
 \subsection[boltzwann]{\tt logical :: geninterp}
 Determines whether to enter the Generic Band Interpolation routines.
@@ -1770,4 +1850,4 @@ \section{Generic Band Interpolation}
 See also the discussion in Sec.~\ref{sec:seedname.geninterp.dat} on
 how to use this flag.
 
-The default value is \verb#true#.
+The default value is \verb#true#.

doc/user_guide/user_guide.tex

@@ -109,6 +109,7 @@
 \newcommand{\wannier}{\texttt{wannier90}}
 \newcommand{\postw}{\texttt{postw90}}
 \newcommand{\bw}{\texttt{BoltzWann}}
+\newcommand{\nw}{\texttt{NerWann}}
 \newcommand{\pwscf}{\textsc{pwscf}}
 \newcommand{\QE}{\textsc{quantum-espresso}}
 \newcommand{\Mkb}{\mathbf{M}^{(\mathbf{k},\mathbf{b})}}

doc/wannier90.bib

@@ -742,4 +742,43 @@ @article{Lihm_shift_eta_2021
   doi = {10.1103/PhysRevB.103.247101},
   url = {https://link.aps.org/doi/10.1103/PhysRevB.103.247101}
 }
-
+@article{jones-zener,
+  title={The theory of the change in resistance in a magnetic field},
+  author={Jones, Harry and Zener, Clarence},
+  journal={Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character},
+  volume={145},
+  number={854},
+  pages={268--277},
+  year={1934},
+  publisher={The Royal Society London}
+}
+@techreport{smith1967electronic,
+  title={Electronic conduction in solids},
+  author={Smith, Arthur C and Janak, James F and Adler, Richard B},
+  year={1967},
+  institution={McGraw-Hill,}
+}
+@book{lundstrom2009fundamentals,
+  title={Fundamentals of carrier transport},
+  author={Lundstrom, Mark},
+  year={2009},
+  publisher={Cambridge university press}
+}
+@article{rezaei2023rta,
+  title={First-principles-aided evaluation of the Nernst coefficient beyond the constant relaxation time approximation},
+  author={Rezaei, S Emad and Zebarjadi, Mona and Esfarjani, Keivan},
+  journal={Computational Materials Science},
+  volume={225},
+  pages={112193},
+  year={2023},
+  publisher={Elsevier}
+}
+@article{rezaei2022crta,
+  title={Calculation of thermomagnetic properties using first-principles density functional theory},
+  author={Rezaei, S Emad and Zebarjadi, Mona and Esfarjani, Keivan},
+  journal={Computational Materials Science},
+  volume={210},
+  pages={111412},
+  year={2022},
+  publisher={Elsevier}
+}

examples/README

@@ -76,3 +76,5 @@ example31: Platinum - Selected columns of density matrix algorithm for spinor wa
 example32: Tungsten - SCDM parameters from projectability 
 
 example33: BC2N - Expansion coefficients for kdotp bands 
+
+example34: InSb - Thermomagnetic effects for InSb