%!TEX root=./user_guide.tex
\chapter{Parameters}

\section{Introduction}

The \texttt{wannier90.x} code described in Part~\ref{part:w90}
calculates the maximally-localized Wannier functions. %The \texttt{wannier90.x} code is a
%serial executable (i.e., it cannot be executed in parallel on different
%CPUs).

The \texttt{postw90.x} executable contains instead a series of modules
that take the Wannier functions calculated by \texttt{wannier90.x} and
use them to calculate different properties.  This executable is
parallel (by means of MPI libraries), so it can be run on multiple
CPUs.  The information on the calculated Wannier functions is read
from the checkpoint \verb|seedname.chk| file. Note that this is
written in an unformatted machine-dependent format. If you need to use
this file on a different machine, or you want to use a version of
\texttt{postw90.x} compiled with a different compiler, refer to
Sec.~\ref{sec:w90chk2chk} in the Appendices for a description of how
to export/import this file. 

\section{Usage}
{\tt postw90.x} can be run in parallel using MPI libraries to
reduce the computation time.

For serial execution use: {\tt postw90.x [seedname]} 

\begin{itemize} \item 
{\tt seedname}: If a seedname string is given the code
will read its input from a file {\tt seedname.win}. The default
  value is {\tt wannier}. One can also equivalently provide the string
  {\tt seedname.win} instead of  {\tt seedname}.
\end{itemize}

For parallel execution use: {\tt mpirun -np NUMPROCS postw90.x [seedname]}

\begin{itemize} \item 
{\tt NUMPROCS}: substitute with the number of processors that you want
to use.
\end{itemize}

Note that the {\tt mpirun} command and command-line flags may be
different in your MPI implementation: read your MPI manual or ask your
computer administrator.

Note also that this requires that the {\tt postw90.x} executable has been
compiled in its parallel version (follow the instructions in the file
{\tt README.install} in the main directory of the wannier90
distribution) and
that the MPI libraries and binaries are installed and correctly
configured on your machine.

\section[seedname.win File]{{\tt seedname.win} File}
The \texttt{postw90.x} uses the same \texttt{seedname.win} input file
of \texttt{wannier90.x}. The input keywords of \texttt{postw90.x} must
thus be added to this file, using the same syntax described in
Sec.~\ref{sec:seednamefile}. 

Note that \texttt{wannier90.x} checks if the syntax of the input file
is correct, but then ignores the value of the flags that refer only to
modules of \texttt{postw90.x}, so one can safely run
\texttt{wannier90.x} on a file that contains also \texttt{postw90.x}
flags.

Similarly, \texttt{postw90.x} ignores flags that refer only to
\texttt{wannier90.x} (as number of iterations, restart flags,
\ldots). However, some parts of the input file must be there, as for
instance the number of Wannier functions, etc.

The easiest thing to do
is therefore to simply \emph{add} the \texttt{postw90} input keywords to
the \texttt{seedname.win} file that was used
to obtain the Wannier functions.

\section{List of available modules}

The currently available modules in \texttt{postw90.x} are:
\begin{itemize}
\item \texttt{dos}: Calculation of the density of states (DOS), projected
  density of states (PDOS), net spin etc.
\item \texttt{kpath}: Calculation of $k$-space quantities such as
  energy bands and Berry curvature along a piecewise linear path in
  the BZ (see examples 17 and 18 of the tutorial).
\item \texttt{kslice}: Calculation of $k$-space quantities on a planar
  slice of the BZ (see examples 17 and 18 of the tutorial).
\item \texttt{berry}: Calculation of properties related to the BZ
  integral of the Berry curvature and Berry connection, including
  anomalous Hall conductivity, orbital magnetisation, optical
  conductivity and nonlinear shift current 
  (see Chap.~\ref{ch:berry} and examples 18, 19 and 25 of the
  tutorial).
\item \texttt{gyrotropic}: Calculation of gyrotropic properties, 
    including natural and current0induced optical rotation, 
and the current-induced magnetization
   (see Chap.~\ref{ch:gyrotropic} and examples  of the
  tutorial).
\item \texttt{BoltzWann}: Calculation of electronic transport
  properties for bulk materials using the semiclassical Boltzmann
  transport equation (see Chap.~\ref{ch:boltzwann} and example 16 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}


\section{Keyword List}
On the next pages the list of available \postw\ input keywords is
reported.  In particular, Table~\ref{parameter_keywords_postw90}
reports keywords that affect the generic behavior of all modules of
\postw. Often, these are ``global'' variables that can be overridden
by module-specific keywords (as for instance the {\tt kmesh}
flag). The subsequent tables describe the input parameters for each
specific module.

A description of the behaviour of the global flags is described
Sec.~\ref{sec:postw90-globalflags}; the description of the flags
specific to the modules can be found in the following sections.

\clearpage

\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{Global Parameters of \postw\ } \\
  \hline
  {\sc kmesh}   & I & Dimensions of the uniform interpolation $k$-mesh 
(one or three integers) \\
  {\sc kmesh\_spacing}& R & Minimum spacing between $k$ points in
  \AA$^{-1}$\\
  {\sc adpt\_smr}   & L & Use adaptive smearing\\
  {\sc adpt\_smr\_fac}   & R & Adaptive smearing prefactor\\
  {\sc adpt\_smr\_max} & P & Maximum allowed value for the adaptive
  energy smearing (eV) \\  
  {\sc smr\_type}   & S &  Analytical form used for the broadened delta function\\
  {\sc smr\_fixed\_en\_width}   & P & Energy smearing (if non-adaptive)\\
  {\sc num\_elec\_per\_state}   & I & Number of electrons per state \\
  \old{\sc scissors\_shift}   & P & Scissors shift applied to the conduction bands (eV) \old{(deprecated)} \\
  {\sc num\_valence\_bands}   & I & Number of valence bands \\
  {\sc spin\_decomp}& L & Decompose various properties into
  up-spin, down-spin, and possibly spin-flip parts\\
  {\sc spin\_axis\_polar}& P & Polar angle of the spin quantization axis (deg)\\
  {\sc spin\_axis\_azimuth}& P & Azimuthal angle of the spin quantization axis (deg)\\
  {\sc spin\_moment}$^*$& L & Determines whether to evaluate the spin 
magnetic moment per cell\\ 
  {\sc uHu\_formatted}& L & Read a formatted {\tt seedname.uHu} file \\
%  {\sc uIu\_formatted}& L & Read a formatted uIu file\\
{\sc spn\_formatted}  & L & 
  Read a formatted {\tt seedname.spn} file\\
  {\sc berry\_curv\_unit} & S & Unit of Berry curvature\\ 
 \hline
\end{tabular}
\caption[Parameter file keywords controlling \postw.]  {{\tt
    seedname.win} file keywords controlling the general behaviour of
  the modules in \postw. 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.\\
  The keyword {\tt spin\_moment} does not affect
    the behavior of the modules in \postw, and does not really belong
    to any of them. It is listed here for lack of a better place.}
\label{parameter_keywords_postw90}
\end{center}
\end{table}


\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{{\tt dos} Parameters} \\
  \hline
  {\sc dos}  & L & Calculate the density of states and related properties\\
  {\sc dos\_task}& S  & List of properties to compute \\
  {\sc dos\_energy\_min} & P & Lower limit of the energy range for
  computing the DOS (eV)\\
  {\sc dos\_energy\_max}& P & Upper limit of the energy range for
  computing the DOS (eV)\\
  {\sc dos\_energy\_step}& R & Step for increasing the energy in the specified range (eV)\\
  {\sc dos\_project}& I & List of WFs onto which the DOS is projected\\
  {\sc [dos\_]kmesh} & I & Dimensions of the uniform interpolation $k$-mesh (one or three integers)\\ 
  {\sc [dos\_]kmesh\_spacing}& R & Minimum spacing between $k$ points in \AA$^{-1}$\\
  {\sc [dos\_]adpt\_smr} & L & Use adaptive smearing for the DOS \\
  {\sc [dos\_]adpt\_smr\_fac} & R & Adaptive smearing prefactor\\
  {\sc [dos\_]adpt\_smr\_max} & P & Maximum allowed value for the adaptive energy smearing (eV) \\
  {\sc [dos\_]smr\_fixed\_en\_width} & P  & Energy smearing (if non-adaptive) for the DOS (eV) \\   
  {\sc [dos\_]smr\_type} & S & Analytical form used for the broadened delta function
  when computing the DOS. \\
  \hline
\end{tabular}
\caption[Parameter file keywords controlling the DOS module.]  {{\tt
    seedname.win} file keywords controlling the {\tt dos}
  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_dos}
\end{center}
\end{table}


\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{{\tt kpath} Parameters} \\
  \hline
  {\sc kpath}  & L & Calculate properties along a piecewise linear path in the BZ \\
  {\sc kpath\_task}& L & List of properties to evaluate\\
  {\sc kpath\_num\_points}& I & Number of points in the first kpath segment\\
  {\sc kpath\_bands\_colour}& S & Property used to colour the energy bands along the path\\
  \hline
\end{tabular}
\caption[Parameter file keywords controlling the kpath module.]  {{\tt
    seedname.win} file keywords controlling the {\tt kpath}
  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_kpath}
\end{center}
\end{table}

\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{{\tt kslice} Parameters} \\
  \hline
  {\sc kslice}  & L & Calculate properties on a slice in the BZ \\
  {\sc kslice\_task}& S & List of properties to evaluate\\
  {\sc kslice\_corner}& R & Position of the corner of the slice\\
  {\sc kslice\_b1}& R & First vector defining the slice\\
  {\sc kslice\_b2}& R & Second vector defining the slice\\
  {\sc kslice\_2dkmesh}& I & Dimensions of the uniform interpolation 
  $k$-mesh on the slice (one or two integers)\\
   \red{\sc kslice\_fermi\_level}& P & \red{This parameter is not used anymore. Use {\sc fermi\_energy} instead.}\\
 {\sc kslice\_fermi\_lines\_colour}& S & Property used to colour the Fermi 
  lines\\
  \hline
\end{tabular}
\caption[Parameter file keywords controlling the kslice module.]
{{\tt seedname.win} file keywords controlling the {\tt kslice}
  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_kslice}
\end{center}
\end{table}



\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{{\tt berry} Parameters} \\
  \hline
  {\sc berry}  & L & Calculate Berry-type quantities \\
  {\sc berry\_task}& L  & List of properties to compute \\
  {\sc [berry\_]kmesh} & I & Dimensions of the uniform interpolation $k$-mesh 
  (one or three integers)\\ 
  {\sc [berry\_]kmesh\_spacing}& R & Minimum spacing between $k$ points in 
  \AA$^{-1}$\\
  {\sc berry\_curv\_adpt\_kmesh} & I & Linear dimension of the adaptively refined $k$-mesh used to compute the anomalous Hall conductivity\\ 
  {\sc berry\_curv\_adpt\_kmesh\_thresh} & P & Threshold magnitude
  of the Berry curvature for adaptive refinement\\ 
  {\sc kubo\_freq\_min} & P & Lower limit of the frequency range for
  optical spectra, JDOS and shift current (eV) \\
  {\sc kubo\_freq\_max}& P & Upper limit of the frequency range for
  optical spectra, JDOS and shift current (eV) \\
  {\sc kubo\_freq\_step}& R &  Step for increasing
the optical frequency in the specified range\\
  {\sc kubo\_eigval\_max}& P &  Maximum energy eigenvalue
  included when evaluating the Kubo-Greenwood conductivity, JDOS and shift current\\
  {\sc [kubo\_]adpt\_smr} & L & Use adaptive energy smearing for the 
  optical conductivity, JDOS and shift current \\
  {\sc [kubo\_]adpt\_smr\_fac} & R & Adaptive smearing prefactor \\
  {\sc[kubo\_]adpt\_smr\_max} & P & Maximum allowed value for the 
  adaptive energy smearing (eV) \\
  {\sc [kubo\_]smr\_type} & S & Analytical form used for the broadened delta function
  when computing the optical conductivity, JDOS and shift current\\  
  {\sc [kubo\_]smr\_fixed\_en\_width} & P  & Energy smearing (if non-adaptive)
  for the optical conductivity, JDOS and shift current (eV) \\
  {\sc sc\_eta} & R  & Energy broadening of energy differences in the sum over virtual states when computing shift current\\
  {\sc sc\_phase\_conv} & I  & Convention for phase factor of Bloch states when computing shift current\\
  {\sc sc\_w\_thr} & R  & Frequency threshold for speeding up delta function integration when computing shift current\\
  \hline
\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}




\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
  \hline
  Keyword & Type & Description \\
  &      &             \\
  \hline\hline
  \multicolumn{3}{|c|}{{\tt berry} Parameters} \\
  \hline
  {\sc gyrotropic}  & L & Calculate gyrotropic quantities \\
  {\sc gyrotropic\_task}& L  & List of properties to compute \\
  {\sc [gyrotropic\_]kmesh} & I & Dimensions of the uniform interpolation $k$-mesh 
  (one or three integers)\\ 
  {\sc [gyrotropic\_]kmesh\_spacing}& R & Minimum spacing between $k$ points in 
  \AA$^{-1}$\\
  {\sc gyrotropic\_freq\_min} & P & Lower limit of the frequency range for
  optical rotation (eV) \\
  {\sc gyrotropic\_freq\_max}& P & Upper limit of the frequency range for
  optical rotation (eV) \\
  {\sc gyrotropic\_freq\_step}& P &  Step for increasing
the optical frequency in the specified range\\
  {\sc gyrotropic\_eigval\_max}& P &  Maximum energy eigenvalue
  included when evaluating the interband natural optical activity\\
  {\sc gyrotropic\_degen\_thresh}& P &  threshold to exclude degenerate bands from the calculation\\
  {\sc [gyrotropic\_]smr\_type} & S & Analytical form used for the broadened delta function\\  
  {\sc [gyrotropic\_]smr\_fixed\_en\_width} & P  & Energy smearing (eV) \\\hline
  {\sc [gyrotropic\_]band\_list} & I  & list of bands used in the calculation \\\hline
  {\sc gyrotropic\_box\_center} & R  &  \multirow{4}{6cm}{The center and three basis vectors, %
defining the box for integration (in reduced coordinates, three real numbers for each vector) } \\
  {\sc gyrotropic\_box\_b1} & R  &  \\
  {\sc gyrotropic\_box\_b2} & R  &  \\
  {\sc gyrotropic\_box\_b3} & R  &  \\
  \hline
\end{tabular}
\caption[Parameter file keywords controlling the Gyrotropic module.]  {{\tt
    seedname.win} file keywords controlling the {\tt gyrotropic}
  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_gyrotropic}
\end{center}
\end{table}



\begin{table}[h!]
\begin{center}
\begin{tabular}{|c|c|p{6cm}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{{\tt BoltzWann} Parameters} \\
\hline
{\sc boltzwann}   & L & Calculate Boltzmann transport coefficients \\
{\sc [boltz\_]kmesh} & I & Dimensions of the uniform interpolation 
$k$-mesh (one or three integers)\\ 
{\sc [boltz\_]kmesh\_spacing} & R & Minimum spacing between $k$ points in \AA$^{-1}$\\
{\sc boltz\_2d\_dir} & S & Non-periodic direction (for 2D systems only)\\
{\sc boltz\_relax\_time} & P & Relaxation time in fs\\
{\sc boltz\_mu\_min} & P & Minimum value of the chemical potential $\mu$ in eV\\
{\sc boltz\_mu\_max} & P & Maximum value of the chemical potential $\mu$ in eV\\
{\sc boltz\_mu\_step} & R & Step for $\mu$ in eV\\
{\sc boltz\_temp\_min} & P & Minimum value of the temperature~$T$ in Kelvin \\
{\sc boltz\_temp\_max} & P & Maximum value of the temperature~$T$ in Kelvin \\
{\sc boltz\_temp\_step} & R & Step for $T$ in Kelvin \\
{\sc boltz\_tdf\_energy\_step} & R & Energy step for the TDF (eV) \\
{\sc boltz\_tdf\_smr\_fixed\_en\_width} & P & Energy smearing for the TDF (eV) \\
{\sc boltz\_tdf\_smr\_type} & S & Smearing type for the TDF \\
{\sc boltz\_calc\_also\_dos} & L & Calculate also DOS while calculating the TDF\\
{\sc boltz\_dos\_energy\_min} & P & Minimum value of the energy for the DOS in eV \\
{\sc boltz\_dos\_energy\_max} & P & Maximum value of the energy for the DOS in eV \\
{\sc boltz\_dos\_energy\_step} & R & Step for the DOS in eV\\
{\sc [boltz\_dos\_]smr\_type} & S & Smearing type for the DOS \\
{\sc [boltz\_dos\_]adpt\_smr} & L & Use adaptive smearing for the DOS \\
{\sc [boltz\_dos\_]adpt\_smr\_fac} & R & Adaptive smearing prefactor\\
{\sc [boltz\_dos\_]adpt\_smr\_max} & P & Maximum allowed value for the
adaptive energy smearing (eV)\\
{\sc [boltz\_dos\_smr\_]fixed\_en\_width} & P  & Energy smearing (if non-adaptive) for the DOS (eV) \\
{\sc boltz\_bandshift} & L & Rigid bandshift of the conduction bands\\
{\sc boltz\_bandshift\_firstband} & I & Index of the first band to shift\\
{\sc boltz\_bandshift\_energyshift} & P & Energy shift of the conduction bands (eV)\\
\hline
\end{tabular}
\caption[Parameter file keywords controlling the \bw\ module.]
{{\tt seedname.win} file keywords controlling the \bw\ module (calculation of the Boltzmann transport coefficients 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}|}
\hline
Keyword & Type & Description \\
        &      &             \\
\hline\hline
\multicolumn{3}{|c|}{{\tt geninterp} Parameters} \\
\hline
{\sc geninterp}   & L & Calculate bands for given set of $k$ points \\
{\sc geninterp\_alsofirstder} & L & Calculate also first derivatives\\ 
{\sc geninterp\_single\_file} & L & Write a single file or one for each
process\\ 
\hline
\end{tabular}
\caption[Parameter file keywords controlling the geninterp module.]
{{\tt seedname.win} file keywords controlling the Generic Band
  Interpolation ({\tt geninterp}) 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_geninterp}
\end{center}
\end{table}

\clearpage
\section{Global variables}
\label{sec:postw90-globalflags}

  \subsection[kmesh]{\tt  integer :: kmesh(:)}  
Dimensions of the interpolation grid used in {\tt postw90.x}.

\emph{Not to be confused with the {\tt mp\_grid} 
input flag, which
  instead specifies the Monkhorst--Pack grid used in the ab-initio calculation!}

If three integers $l$ $m$ $n$ are given, the reciprocal-space cell
subtended by the three primitive translations is sampled on a uniform
$l\times m\times n$ grid (including $\Gamma$).  If only one integer $m$ is given, an
$m\times m\times m$ grid is used.

If you use a module which needs a k-mesh, either {\tt kmesh\_spacing} or {\tt
  kmesh} must be defined.

  \subsection[kmesh\_spacing]{\tt real(kind=dp) :: kmesh\_spacing}
An alternative way of specifying the interpolation grid.
This flag defines the minimum distance for
neighboring $k$ points along each of the three directions in $k$
space. 

The units are \AA$^{-1}$.

If you use a module which needs a k-mesh, either {\tt kmesh\_spacing} or {\tt
  kmesh} must be defined.

\subsection[adpt\_smr]{\tt logical :: adpt\_smr}
Determines whether to use an adaptive scheme for broadening the
DOS and similar quantities defined on the energy axis.
If \verb#true#, the values for the smearing widths are 
controlled by the flag {\tt adpt\_smr\_fac}.

The default value is \verb#true#.

\subsection[adpt\_smr\_fac]{\tt real(kind=dp) :: adpt\_smr\_fac}

The width $\eta_{n{\bf k}}$ of the broadened delta function used to
determine the contribution to the spectral property (DOS, ...) from
band $n$ at point ${\bf k}$ is calculated as
%
$$
\eta_{n{\bf k}}=\alpha\vert \nabla_{\bf k}
\varepsilon_{n{\bf k}}\vert \Delta k,
$$ 
%
where $\varepsilon_{n{\bf k}}$ is the energy eigenvalue and the
dimensionless factor $\alpha$ is given by {\tt
  adpt\_smr\_fac}. $\Delta k$ is taken to be the largest of the mesh
spacings along the three reciprocal lattice vectors ${\bf b_1}$, ${\bf
  b_2}$, and ${\bf b_3}$.  If the calculated value of $\eta_{n{\bf
    k}}$ exceeds {\tt adpt\_smr\_max}, the latter value is used.

The default value is $\sqrt{2}$.

\subsection[adpt\_smr\_max]{\tt real(kind=dp) ::
  adpt\_smr\_max}

See description given immediately above.

The units are eV. The default value is 1.0.

\subsection[smr\_type]{\tt  character(len=120) :: smr\_type}

Defines the analytical form used for the broadened delta function in
the computation of the DOS and similar quantities defined on the
energy axis.

\begin{itemize}
  
\item
  {\tt gauss}: Gaussian smearing

\item
  {\tt m-pN}: derivative of the $N$-th order
    Methfessel-Paxton function ($N\geq 0$). Example: {\tt m-p2} for the
  second-order Methfessel-Paxton function. If only {\tt m-p} is
  provided, the first-order function is used, i.e., it is equivalent to {\tt m-p1}.

\item
  {\tt m-v} or {\tt cold}: derivative of the Marzari--Vanderbilt cold-smearing function

\item
  {\tt f-d}: derivative of the Fermi-Dirac distribution function

\end{itemize}

The default value is {\tt gauss}.

\subsection[smr\_fixed\_en\_width]{\tt logical :: smr\_fixed\_en\_width}
Energy width for the smearing function for the DOS. Used only if {\tt
  adpt\_smr} is \verb#false#.

The units are eV. The default value is 0~eV. Note that if the width is
smaller than twice the energy step (e.g. {\tt dos\_energy\_step} for
the {\tt dos} module), the DOS
will be unsmeared (thus the default is to have an unsmeared
properties when {\tt  adpt\_smr} is set to \verb#false#.).


  \subsection{\tt integer :: num\_elec\_per\_state} 
Number of electrons per state. It can only take the values one or
two.

The default value is 1 if {\tt spinors=true}, 2 otherwise.

  \subsection{\tt real(kind=dp) :: scissors\_shift} 
Scissors shift applied to the conduction bands.

\textbf{Note!} This variable is deprecated and will be removed in future
versions of the code. This applies the scissors shift only to the Hamiltonian,
but also other matrices might need to be updated if a scissors shift is 
applied. If you are using BoltzWann, consider using \texttt{boltz\_bandshift} instead.

The units are eV. The default value is 0~eV (i.e., no scissors shift applied).

  \subsection{\tt integer :: num\_valence\_bands} 
Number of valence bands of the system. Used in different modules and
for the scissors shift.

No default value.


\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).

For the {\tt dos} and {\tt BoltzWann} 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
by the input variables {\tt spin\_axis\_polar} and {\tt
  spin\_axis\_azimuth}).  For the {\tt berry} module with {\tt
  berry\_task = kubo}, three extra columns are added to {\tt
  seedname-jdos.dat}, containing the decomposition of the JDOS into up
$\rightarrow$ up, down $\rightarrow$ down, and spin-flip
transitions. In the same way, six extra columns are added to the data
files {\tt seedname-kubo*.dat} where the complex optical conductivity
is stored.

The file {\tt seedname.spn} must be present at input. Furthermore, if
this variable is set to \verb#true# it
requires {\tt num\_elec\_per\_state = 1}.

The default value is \verb#false#.

  \subsection{\tt real(kind=dp) :: spin\_axis\_polar}
Polar angle of the spin quantization axis.

The units are degrees. The default value is 0.

\subsection{\tt real(kind=dp) :: spin\_axis\_azimuth}
Azimuthal angle of the spin quantization axis. 

The units are degrees. The default value is 0.

\subsection[spin\_moment]{\tt logical :: spin\_moment}
Determines whether to evaluate the spin moment.

The default value is \verb#false#.

\subsection[uHu\_formatted]{\tt logical :: uHu\_formatted}

If \verb#uHu_formatted#=\verb#true#, then the uHu matrix elements will be
read from disk as formatted (ie ASCII) files; otherwise they will be
read as unformatted files.

The default value of this parameter is $\verb#false#$.

%\subsection[uIu\_formatted]{\tt character(len=20) :: uIu\_formatted}

%If \verb#uIu_formatted#=\verb#TRUE#, then the uIu matrix elements will be
%read from disk as formatted (ie ASCII) files; otherwise they will be
%read as unformatted files.

%The default value of this parameter is $\verb#false#$.

\subsection[spn\_formatted]{\tt logical :: spn\_formatted}

If \verb#spn_formatted#=\verb#true#, then the spin matrix elements
will be read from disk as formatted (ie ASCII) files; otherwise they
will be read as unformatted files. Unformatted is generally preferable
as the files will take less disk space and I/O is significantly
faster. However such files will not be transferable between all
machine architectures and formatted files should be used if
transferability is required (i.e., for test cases).

The default value is \verb#false#.


\subsection[spn\_formatted]{\tt character(len=20) :: berry\_curv\_unit}

Unit in which the Berry curvature is specified at input (in {\tt
  berry\_curv\_adpt\_kmesh\_thresh}) or written to file (when {\tt
  kpath\_task=curv} or {\tt kslice\_task=curv}).

\begin{itemize}

\item
  {\tt ang2}: Angstrom$^2$

\item
  {\tt bohr2}: Bohr$^2$ (atomic units)

\end{itemize}

The default value is {\tt ang2}.

\subsection{\tt real(kind=dp) :: sc\_eta}

The width $\eta$ used to broaden energy differences in denominators of the form 
%
$$
\frac{1}{\varepsilon_{n\bf{k}}-\varepsilon_{m\bf{k}}}\rightarrow
\text{Re}\frac{1}{\varepsilon_{n\bf{k}}-\varepsilon_{m\bf{k}}+i\eta}.
$$ 
%
The above is needed in shift-current calculations in order to avoid numerical problems
caused by near-degeneracies in the sum over virtual states. 

The units are eV. The default value is 0.4.


\subsection{\tt integer :: sc\_phase\_conv}

Convention for the expansion of the Bloch states in shift-current calculations. It can only take the values one or two.
We follow the convention of Ref.~\cite{pythtb}:
\begin{itemize}

\item
  1: Include Wannier centre ${\bm \tau}_{n}=\langle w_{n{\bf 0}}|{\bf r}| w_{n{\bf 0}} \rangle$ in the phase factor
  (so-called tight-binding convention):
%
$$
|u_{n\bf{k}}\rangle = \sum_{\bf{R}} e^{-i{\bf k}({\bf r}-{\bf R}-{\bm \tau}_{n})}| w_{n\bf{R}} \rangle
$$ 
%

\item
  2: Do not include Wannier centre in the phase factor (usual \verb|Wannier90| convention):
%
$$
|u_{n\bf{k}}\rangle = \sum_{\bf{R}} e^{-i\bf{k}(\bf{r}-\bf{R})}| w_{n\bf{R}} \rangle
$$ 
%
\end{itemize}
The convention does not affect the full shift-current matrix element, but it does affect
the weights of the internal components that compose it (see Ref. \cite{ibanez-azpiroz_ab_2018}). 

The default value is 1. 


\subsection{\tt real(kind=dp)  :: sc\_w\_thr}

Parameter $\alpha_{t}$ for speeding up the frequency integration in shift-current calculations.
It settles the frequency threshold $\omega_{t}=\alpha_{t}\eta_{n{\bf k}}$
(a factor times the broadening)
beyond which the delta functions are taken as zero. 


The default value is 5.0. 






\clearpage
\section{DOS}
Note that the behavior of the \verb#dos# module  is also influenced by
the value of some global flags (listed in
Table~\ref{parameter_keywords_postw90}), as
\verb#spin_decomp#, \verb#spin_axis_polar#, \verb#spin_axis_azimuth#,
\verb#scissors_shift#, etc.
Some of the global flags can be possibly
overridden by local flags of the DOS module, listed below, which have
the same name of the global flag but are prefixed by \verb#dos_#.

\subsection[dos]{\tt logical :: dos}
Determines whether to enter the DOS routines.

The default value is \verb#false#.


\subsection[dos\_task]{\tt character(len=20) ::  dos\_task}
The quantity to compute when {\tt dos=true}

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#dos_plot# Density of states. An output data file
  {\tt seedname-dos.dat} is created, containing the energy values in
  eV in the first column, and the total DOS per unit cell and unit
  energy range (in eV$^{-1}$) in the second. Two additional columns
  are present if {\tt spin\_decomp=true}
\end{itemize}


The default value is \verb#dos_plot#.


\subsection[dos\_min\_energy]{\tt real(kind=dp) :: dos\_energy\_min}
Lower limit of the energy range for computing the DOS.
Units are eV.

The default value is the minimum value of the energy eigenvalues
stored in {\tt seedname.eig}, minus 0.6667.

\subsection[dos\_max\_energy]{\tt real(kind=dp) :: dos\_energy\_max}
Upper limit of the energy range for computing the DOS.
Units are eV.

If an inner energy window was specified, 
the default value is the upper bound of the innter energy window, plus 0.6667.
Otherwise it is  the maximum value of the energy eigenvalues
stored in {\tt seedname.eig}, plus 0.6667.

\subsection[dos\_energy\_step]{\tt real(kind=dp) :: dos\_energy\_step}
Energy step for the grid of energies used to plot the dos. Units are eV.

The default value is 0.01~eV.

\subsection[dos\_project]{\tt integer :: dos\_project(:)}

If present {\tt postw90} computes, instead of the total DOS, the
partial DOS projected onto the WFs listed. The WFs are numbered
according to the file {\tt seedname.wout}.

For example, to project onto WFs 2, 6, 7, 8, and 12:

{\tt dos\_project : 2, 6-8, 12}

The DOS projected onto a set ${\cal S}$ of orbitals is calculated as
%
\begin{align}
\rho_{\cal S}(E)&=\frac{1}{N_k}\sum_{\bf k}\sum_n
\langle \psi_{n\bf k}^{({\rm H})}\vert \hat{P}_{\bf k}({\cal S})\vert 
\psi_{n\bf k}^{({\rm H})}\rangle\delta(\varepsilon_{n\bf k}-E)\\
\hat{P}_{\bf k}({\cal S})&=\sum_{m\in{\cal S}}
\vert \psi_{n\bf k}^{({\rm W})}\rangle\langle \psi_{n\bf k}^{({\rm W})}\vert,
\end{align}
%
where $N_k$ is the number of mesh points used to sample the BZ, and
the superscript (H) and (W) refer to {\it Hamiltonian gauge} and {\it
  Wannier gauge}~\cite{wang-prb06}.

\subsection[dos\_kmesh]{\tt integer :: dos\_kmesh(:)}
Overrides the \verb#kmesh# global variable (see Sec.~\ref{sec:postw90-globalflags}).

\subsection[dos\_kmesh\_spacing]{\tt real(kind=dp) :: dos\_kmesh\_spacing}
Overrides the \verb#kmesh_spacing# global variable (see Sec.~\ref{sec:postw90-globalflags}).

\subsection[dos\_adpt\_smr]{\tt logical :: dos\_adpt\_smr}
Overrides the \verb#adpt_smr# global variable (see Sec.~\ref{sec:postw90-globalflags}).

\subsection[dos\_adpt\_smr\_fac]{\tt real(kind=dp) :: dos\_adpt\_smr\_fac}
Overrides the \verb#adpt_smr_fac# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[dos\_adpt\_smr\_max]{\tt real(kind=dp) ::
  dos\_adpt\_smr\_max}
Overrides the \verb#adpt_smr_max# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[dos\_smr\_fixed\_en\_width]{\tt logical :: dos\_smr\_fixed\_en\_width}
Overrides the \verb#smr_fixed_en_width# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

Note that if the width is smaller than twice the energy step {\tt dos\_energy\_step}, the DOS
will be unsmeared (thus the default is to have an unsmeared DOS).


\subsection[dos\_smr\_type]{\tt  character(len=20) :: dos\_smr\_type}
Overrides the \verb#smr_type# global variable (see Sec.~\ref{sec:postw90-globalflags}).


\clearpage
\section{kpath}

\subsection[berry]{\tt logical :: kpath}
Determines whether to enter the kpath routines.

The default value is \verb#false#.


\subsection[kpath\_task]{\tt character(len=20) ::  kpath\_task} 
The quantities to plot when {\tt kpath=true} 

The valid options for this parameter are:
\begin{itemize}

\item[{\bf --}] \verb#bands# Energy bands, in eV. The following files
  are created:
\begin{itemize}
  
   \item[$\cdot$] {\tt seedname-bands.dat} (data file) 

   \item[$\cdot$] {\tt seedname-bands.gnu} ({\tt gnuplot} script)

   \item[$\cdot$] {\tt seedname-bands.py} ({\tt python} script)

   \item[$\cdot$] {\tt seedname-path.kpt} (list of $k$-points along
     the path, written in the {\tt pwscf} format)

\end{itemize}

\item[{\bf --}] \verb#curv# Minus the Berry curvature given by
  Eq.~(\ref{eq:curv-occ}) of Ch.~\ref{ch:berry}, in units of {\tt
    berry\_curv\_unit}. The following files are created:

\begin{itemize}

   \item[$\cdot$] {\tt seedname-curv.dat} (data file) 

   \item[$\cdot$] {\tt seedname-curv\_\{x,y,z\}.gnu} ({\tt gnuplot} scripts)

   \item[$\cdot$] {\tt seedname-curv\_\{x,y,z\}.py} ({\tt python} scripts)

\end{itemize}

\item[{\bf --}] \verb#morb# The integrand of the $k$-space orbital
  magnetization formula [Eq.~(\ref{eq:morb-k}) of Ch.~\ref{ch:berry}]
  in eV$\cdot$\AA$^2$. Four output files are created:

\begin{itemize}

   \item[$\cdot$] {\tt seedname-morb.dat} (data file)

   \item[$\cdot$] {\tt seedname-morb\_\{x,y,z\}.gnu} ({\tt gnuplot}
     scripts)

   \item[$\cdot$] {\tt seedname-morb\_\{x,y,z\}.py} ({\tt python}
     scripts)

\end{itemize}

\item[{\bf --}] Any combination of the above.  The following
  combinations are of special interest

{\tt kpath\_task = bands+curv}

{\tt kpath\_task = bands+morb}

They generate the following files:
\begin{itemize}
  
   \item[$\cdot$] {\tt seedname-bands.dat} (data file) 

   \item[$\cdot$] {\tt seedname-\{curv,morb\}.dat} (data file) 

   \item[$\cdot$] {\tt seedname-bands+\{curv,morb\}\_\{x,y,z\}.py}
     ({\tt python} scripts)

\end{itemize}

Two-panel figures are produced, with the energy bands within $\pm
0.65$~eV of the Fermi level in the top panel, and the Berry curvature
(or $k$-space orbital magnetization) in the bottom panel.
\end{itemize}

The default value is {\tt bands}.


\subsection[kpath\_num\_points]{\tt integer :: kpath\_num\_points}

If $\verb#kpath#=\verb#true#$, then the number of points along
the first section of the bandstructure plot given by
\verb#kpoint_path#. Other sections will have the same density of
$k$-points. 

The default value is 100.


\subsection[kpath\_colour]{\tt character(len=20) ::
  kpath\_bands\_colour}
When {\tt kpath\_task=bands}, colour code the energy bands according
to the specified quantity.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#spin# Spin projection (in units of $\hbar/2$)
  along the quantization axis defined by the variables {\tt
    spin\_axis\_polar} and {\tt spin\_axis\_azimuth}, for a spinor
  calculation
\item[{\bf --}]  \verb#none# no colour coding
\end{itemize}

The default value is {\tt none}.


\clearpage
\section{kslice}

\subsection[berry]{\tt logical :: kslice}
Determines whether to enter the kslice routines.

The default value is \verb#false#.

\subsection[kslice\_task]{\tt character(len=20) ::  kslice\_task}
The quantity to plot when {\tt kslice=true} 

The valid options for this parameter are:
\begin{itemize}

\item[{\bf --}] \verb#fermi_lines# Lines of intersection between
  constant-energy surfaces and the slice. The energy level is
  specified by the keyword {\tt fermi\_energy}. Output files:

  \begin{itemize}

  \item[$\cdot$] {\tt seedname-kslice-fermi-spn.dat} (data file when
    {\tt kslice\_fermi\_lines\_colour = spin})

  \item[$\cdot$] {\tt seedname-bnd\_n.dat} ({\tt gnuplot} data files
    when {\tt kslice\_fermi\_lines\_colour = none})

  \item[$\cdot$] {\tt seedname-kslice-coord.dat} ({\tt python} data
    files when {\tt kslice\_fermi\_lines\_colour = none})

  \item[$\cdot$] {\tt seedname-kslice-bands.dat} ({\tt python} data
    file when {\tt kslice\_fermi\_lines\_colour = none})

  \item[$\cdot$] {\tt seedname-kslice-fermi\_lines.gnu} ({\tt gnuplot}
    script)

  \item[$\cdot$] {\tt seedname-kslice-fermi\_lines.py} ({\tt python}
    script)

  \end{itemize}

\item[{\bf --}] \verb#curv#[+\verb#fermi_lines#] Heatmap of the Berry
  curvature of the occupied states [together with the constant-energy
  contours]. The unit of Berry curvature is {\tt berry\_curv\_unit}.

Output files:

  \begin{itemize}

  \item[$\cdot$] {\tt seedname-kslice-coord.dat} (data files)
    
  \item[$\cdot$] {\tt seedname-kslice-curv.dat} (data file)

  \item[$\cdot$] [{\tt seedname-kslice-bands.dat}] (data file)
    
  \item[$\cdot$] {\tt seedname-kslice-curv\_\{x,y,z\}[+fermi\_lines].py} ({\tt
      python} scripts) 
    
  \end{itemize}

\item[{\bf --}] \verb#morb#[+\verb#fermi_lines#] Heatmap of the
  $k$-space orbital magnetization in eV$\cdot$\AA$^2$ [together with
  the constant-energy contours]. Output files:

  \begin{itemize}

  \item[$\cdot$] {\tt seedname-kslice-coord.dat} (data files)
    
  \item[$\cdot$] {\tt seedname-kslice-morb.dat} (data file)

  \item[$\cdot$] [{\tt seedname-kslice-bands.dat}] (data file)
    
  \item[$\cdot$] {\tt seedname-kslice-morb\_\{x,y,z\}[+fermi\_lines].py} ({\tt
      python} scripts)
    
  \end{itemize}

\end{itemize}

The default value is {\tt fermi\_lines}.

Note: When {\tt kslice\_fermi\_lines\_colour = none} the {\tt gnuplot}
scripts draw the $k$-slices with a square shape, even when {\tt
  kslice\_b1} and {\tt kslice\_b2} below are not at right angles, or
do not have equal lengths.  (The {\tt python} scripts draw the slices
with the correct parallelogram shape.)

\subsection[kslice\_corner]{\tt real(kind=dp) :: kslice\_corner(3)}
Reduced coordinates of the lower-left corner of the slice in k-space.

The default value is $(0.0,0.0,0.0)$

\subsection[kslice\_corner]{\tt real(kind=dp) :: kslice\_b1(3)}
Reduced coordinates of the first reciprocal-space vector 
defining the slice.

The default value is $(1.0,0.0,0.0)$.

\subsection[kslice\_corner]{\tt real(kind=dp) :: kslice\_b2(3)}
Reduced coordinates of the second reciprocal-space vector 
defining the slice.

The default value is $(0.0,1.0,0.0)$.

\subsection[kslice\_num\_points]{\tt integer :: kslice\_2dkmesh(2)}

Dimensions of the $k$-point grid covering the slice.
If two integers $m$ $n$ are given, the slice is sampled on a uniform
$m\times n$ grid.  If only one integer $m$ is given, an $m\times m$
grid is used.

The default value for \verb#kslice_kmesh# is 50.


\subsection[kpath\_colour]{\tt character(len=20) ::
  kslice\_fermi\_lines\_colour}
When {\tt kslice\_task=fermi\_lines} (but not when combined with {\tt
  curv} or {\tt morb}), colour code the Fermi lines according to the
specified quantity.

The valid options for this parameter are:
\begin{itemize}
\item[{\bf --}] \verb#spin# Spin projection (in units of $\hbar/2$)
  along the quantization axis defined by the variables {\tt
    spin\_axis\_polar} and {\tt spin\_axis\_azimuth}, for a spinor
  calculation
\item[{\bf --}]  \verb#none# no colour coding
\end{itemize}

The default value is {\tt none}.


\clearpage
\section{berry}

\subsection[berry]{\tt logical :: berry}
Determines whether to enter the berry routines.

The default value is \verb#false#.


\subsection[berry\_task]{\tt character(len=120) ::  berry\_task}
The quantity to compute when {\tt berry=true}

The valid options for this parameter are:

\begin{itemize}


\item[{\bf --}] \verb#kubo# Complex optical conductivity and joint
  density of states. Output files:

\begin{itemize}

\item[$\cdot$] {\tt seedname-kubo-S\_{\{xx,yy,zz,xy,xz,yz\}.dat}}
  (data files).  First column: optical frequency $\hbar\omega$ in
  eV. Second and third columns: real and imaginary parts of the
  symmetric conductivity $\sigma^{\rm
    S}_{\alpha\beta}(\hbar\omega)=\sigma^{\rm
    S}_{\beta\alpha}(\hbar\omega)$ in S/cm. Six additional columns are
  present if {\tt spin\_decomp = true}.

\item[$\cdot$] {\tt seedname-kubo-A\_{\{yz,zx,xy\}.dat}} (data files).
  First column: optical frequency $\hbar\omega$ in eV. Second and
  third columns: real and imaginary parts of the antisymmetric
  conductivity $\sigma^{\rm A}_{\alpha\beta}(\hbar\omega)=-\sigma^{\rm
    A}_{\beta\alpha}(\hbar\omega)$ in S/cm. Six additional columns are
  present if {\tt spin\_decomp = true}.


\item[$\cdot$] {\tt seedname-jdos.dat} (data file).  First column:
  energy difference $\hbar\omega$ in eV between conduction ($c$) and
  valence ($v$) states with the same crystal momentum ${\bf
    k}$. Second column: joint density of states
  $\rho_{cv}(\hbar\omega)$ (number of states per unit cell per unit
  energy range, in eV$^{-1}$). Three additional columns are present if
  {\tt spin\_decomp = true}.


\end{itemize}

\item[{\bf --}] \verb#ahc# Anomalous Hall conductivity, in S/cm.  The
  three independent components $\sigma_x=\sigma_{yz}$,
  $\sigma_y=\sigma_{zx}$, and $\sigma_z=\sigma_{xy}$ are
  computed. Output files:

\begin{itemize}

\item[$\cdot$] {\tt seedname-ahc-fermiscan.dat} (data file) . The
  first column contains the Fermi level $\varepsilon_F$ in eV, and the
  following three column the values of
  $\sigma_{x,y,z}(\varepsilon_F)$.  This file is written if a range of
  Fermi energies is specified via {\tt fermi\_energy\_min} and {\tt
    fermi\_energy\_max}.  If a single Fermi energy is given, the AHC
  is printed in {\tt seedname.wpout} only.

\end{itemize}

\item[{\bf --}] \verb#morb# Orbital magnetisation, in bohr magnetons
  per cell.

Output files:

\begin{itemize}

\item[$\cdot$] {\tt seedname-morb-fermiscan.dat} (data file). The
  first column contains the Fermi level $\varepsilon_F$ in eV, and the
  following three column the values of $M^{\rm
    orb}_{x,y,z}(\varepsilon_F)$.  This file is written if a range of
  Fermi energies is specified via {\tt fermi\_energy\_min} and {\tt
    fermi\_energy\_max}.  If a single Fermi energy is given, ${\bf
    M}^{\rm orb}$ is printed in {\tt seedname.wpout} only.

\end{itemize}

\end{itemize}
There is no default value.


\subsection[berry\_kmesh]{\tt integer :: berry\_kmesh(:)}
Overrides the \verb#kmesh# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[berry\_kmesh\_spacing]{\tt real(kind=dp) ::
  berry\_kmesh\_spacing}
Overrides the \verb#kmesh_spacing# global variable (see
Sec.~\ref{sec:postw90-globalflags}).


\subsection[berry\_adpt\_kmesh]{\tt integer :: berry\_curv\_adpt\_kmesh}
If a positive integer $n$ is given and {\tt berry\_task=ahc}, an
$n\times n\times n$ mesh is placed around points on the uniform mesh
(defined by either {\tt berry\_kmesh} or {\tt berry\_kmesh\_spacing})
where the magnitude of the $k$-space Berry curvature exceeds the
threshold value specified in {\tt
  berry\_curv\_adpt\_kmesh\_thresh}. This can be used to densify the
BZ integration mesh around spikes in the Berry curvature.

The default value is 1.


\subsection[berry\_adpt\_kmesh\_thresh]{\tt real(kind=dp) ::
  berry\_curv\_adpt\_kmesh\_thresh}

Magnitude of the Berry curvature (in units of {\tt berry\_curv\_unit})
that triggers adaptive mesh refinement when {\tt berry\_task=ahc}.

The default value is 100.0.


\subsection[optics\_energy\_min]{\tt real(kind=dp) :: kubo\_freq\_min}
Lower limit of the frequency range for computing the optical conductivity
and JDOS. Units are eV.

The default value 0.0.

\subsection[optics\_energy\_max]{\tt real(kind=dp) :: kubo\_freq\_max}
Upper limit of the frequency range for computing the optical conductivity
and JDOS. Units are eV.

If an inner energy window was specified, the default value is {\tt
  dis\_froz\_max}-{\tt fermi\_energy}+0.6667.  Otherwise it is the
difference between the maximum and the minimum energy eigenvalue
stored in {\tt seedname.eig}, plus 0.6667.


\subsection[optics\_energy\_step]{\tt real(kind=dp) :: kubo\_freq\_step}
Difference between consecutive values of the optical frequency
between {\tt kubo\_freq\_min} and {\tt kubo\_freq\_max}. Units are eV.

The default value is 0.01.


\subsection[optics\_energy\_max]{\tt real(kind=dp) ::
  kubo\_eigval\_max}
Maximum energy eigenvalue of the eigenstates to be included in the
evaluation of the optical conductivity and JDOS.  Units are eV.

If an inner energy window was specified, the default value is the
upper bound of the inner energy window plus 0.6667.  Otherwise it is
the maximum energy eigenvalue stored in {\tt seedname.eig} plus
0.6667.

\subsection[optics\_adpt\_smr]{\tt logical :: kubo\_adpt\_smr}
Overrides the \verb#adpt_smr# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[optics\_adpt\_smr\_fac]{\tt real(kind=dp) ::
  kubo\_adpt\_smr\_fac}
Overrides the \verb#adpt_smr_fac# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[optics\_adpt\_smr\_max]{\tt real(kind=dp) ::
  kubo\_adpt\_smr\_max}
Overrides the \verb#adpt_smr_max# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[optics\_smr\_fixed\_en\_width]{\tt logical :: 
kubo\_smr\_fixed\_en\_width}
Overrides the \verb#smr_fixed_en_width# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[optics\_smr\_type]{\tt  character(len=120) :: 
kubo\_smr\_type}
Overrides the \verb#smr_type# global variable (see
Sec.~\ref{sec:postw90-globalflags}).


\clearpage
\section{Gyrotropic}

\subsection[gyrotropic]{\tt logical :: gyrotropic}
Determines whether to enter the gyrotropic routines.

The default value is \verb#false#.


\subsection[gyrotropic\_task]{\tt character(len=120) ::  gyrotropic\_task}
The quantity to compute when {\tt gyrotropic=true}

May contain one or more of the following valid options (note that each option starts with a '-'):

\begin{itemize}

\item \verb#-D0#  The Berry-curvature dipole tensor \eq{D_ab} (dimensionless) \\
Output file: {\tt seedname-gyrotropic-D.dat}
( see Sec. \ref{sec:gyrotropic:format} for file format description)

\item \verb#-Dw# The finite-frequency  Berry-curvature dipole tensor \eq{D-tilde} (dimensionless) \\
Output file: {\tt seedname-gyrotropic-tildeD.dat}
( see Sec. \ref{sec:gyrotropic:format} for file format description)


\item \verb#-C# The ohmic conductivity tensor \eq{C_ab} (Ampere/cm) \\
Output file: {\tt seedname-gyrotropic-C.dat}
( see Sec. \ref{sec:gyrotropic:format} for file format description)

\item \verb#-K# The orbital contribution to the kME tensor \eq{K_ab} (Ampere) \\
Output file: {\tt seedname-gyrotropic-K\_orb.dat}
( see Sec. \ref{sec:gyrotropic:format} for file format description)
    \begin{itemize}
	\item[$\circ$] \verb#-spin# : if this task is present, compute also the spin contribution.\\
	Output file: {\tt seedname-gyrotropic-K\_spin.dat}
    \end{itemize}

\item \verb#-NOA# The orbital contribution to the NOA \eq{K_ab} (\AA) \\
Output file: {\tt seedname-gyrotropic-NOA\_orb.dat}
( see Sec. \ref{sec:gyrotropic:format} for file format description)
    \begin{itemize}
	\item[$\circ$] \verb#-spin# : if this task is present, compute also the spin contribution. \\
	Output file: {\tt seedname-gyrotropic-NOA\_spin.dat}
    \end{itemize}

\item \verb#-dos# the density of states
Output file: {\tt seedname-gyrotropic-DOS.dat}. First column - energy (eV), second column - DOS ($1/(\mathrm{eV}\times\mathrm{\AA}^3)$)

\end{itemize}

There is no default value.

\subsection{output data format \label{sec:gyrotropic:format}}
The calculated tensors are written as functions of Fermi level $E_F$ (first column) 
and frequency $\omega$ (second column).
If the tensor does not denend on $\omega$, the second column is filled by zeros. 
Data is grouped in blocks of the same $\omega$ separated by two blank lines.
In case of natural optical activity the columns 3 to 11 contain the independent 
components of $\gamma_{abc}$ (antisymmetric in $ab$): $yzx$, $zxy$ ,$xyz$, $yzy$, $yzz$, $zxz$, $xyy$, $yzz$ and $zxx$.
For tensors $C_{ab}$, $D_{ab}$, $\widetilde D_{ab}$, $K_{ab}$ the symmetric and antisymmetric components are writted.
Thus, the columns 3 to 11 are marked as $xx$, $yy$, $zz$, $xy$, $xz$, $yz$, $x$, $y$, $z$, wich correspond ,e.g., for $D_{ab}$ to 
$D_{xx}$, $D_{yy}$, $D_{zz}$, $(D_{xy}+D_{yx})/2$, $(D_{xz}+D_{zx})/2$, $(D_{yz}+D_{zy})/2$, $(D_{yz}-D_{zy})/2$, $(D_{zx}-D_{xz})/2$, $(D_{xy}-D_{yx})/2$

\subsection[gyrotropic\_kmesh]{\tt integer :: gyrotropic\_kmesh(:)}
Overrides the \verb#kmesh# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[gyrotropic\_kmesh\_spacing]{\tt real(kind=dp) ::
  gyrotropic\_kmesh\_spacing}
Overrides the \verb#kmesh_spacing# global variable (see
Sec.~\ref{sec:postw90-globalflags}).


\subsection[gyrotropic\_freq\_min]{\tt real(kind=dp) :: gyrotropic\_freq\_min}
Lower limit of the frequency range for computing the optical activity. 

Units are eV.
The default value 0.0.

\subsection[gyrotropic\_freq\_max]{\tt real(kind=dp) :: gyrotropic\_freq\_max}
Upper limit of the frequency range for computing the optical activity. Units are eV.

If an inner energy window was specified, the default value is {\tt
  dis\_froz\_max}-{\tt fermi\_energy}+0.6667.  Otherwise it is the
difference between the maximum and the minimum energy eigenvalue
stored in {\tt seedname.eig}, plus 0.6667.

\subsection[gyrotropic\_freq\_step]{\tt real(kind=dp) :: gyrotropic\_freq\_step}
Difference between consecutive values of the optical frequency
between {\tt gyrotropic\_freq\_min} and {\tt gyrotropic\_freq\_max}. 

Units are eV.
The default value is 0.01.

\subsection[gyrotropic\_eigval\_max]{\tt real(kind=dp) ::  gyrotropic\_eigval\_max}
Maximum energy eigenvalue of the eigenstates to be included in the
evaluation of the Natural optical activity.   Units are eV.

If an inner energy window was specified, the default value is the
upper bound of the inner energy window plus 0.6667.  Otherwise it is
the maximum energy eigenvalue stored in {\tt seedname.eig} plus
0.6667.

\subsection[gyrotropic\_smr\_fixed\_en\_width]{\tt logical :: gyrotropic\_smr\_fixed\_en\_width}
Overrides the \verb#smr_fixed_en_width# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[gyrotropic\_smr\_type]{\tt  character(len=120) :: gyrotropic\_smr\_type}
Overrides the \verb#smr_type# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[gyrotropic\_degen\_thresh]{\tt  character(len=120) :: gyrotropic\_degen\_thresh}
The threshould to eliminate degenerate bands from the calculation
in order to avoid divergences.

Units are eV. The  dfault value is 0.

\subsection[gyrotropic\_box\_center]{\tt  character(len=120) :: gyrotropic\_box\_center} - three real numbers.
Optionally the integration may be restricted to a parallelogram, centered at {\tt gyrotropic\_box\_center}
and defined by vectors {\tt gyrotropic\_box\_b\{1,2,3\}}

In reduced coordinates. Default value is 0.5 0.5 0.5

\subsection[gyrotropic\_box\_b1]{\tt  character(len=120) :: gyrotropic\_box\_b1} - three real numbers.
In reduced coordinates. Default value is 1.0 0.0 0.0

\subsection[gyrotropic\_box\_b2]{\tt  character(len=120) :: gyrotropic\_box\_b2} - three real numbers.
In reduced coordinates. Default value is 0.0 1.0 0.0

\subsection[gyrotropic\_box\_b3]{\tt  character(len=120) :: gyrotropic\_box\_b3} - three real numbers.
In reduced coordinates. Default value is 0.0 0.0 1.0

\clearpage
\section{BoltzWann}
\subsection[boltzwann]{\tt logical :: boltzwann}
Determines whether to enter the \bw\ routines.

The default value is \verb#false#.

\subsection[boltz\_kmesh]{\tt integer :: boltz\_kmesh(:)}
It determines the interpolation $k$ mesh used to calculate the TDF (from which the transport coefficient are calculated). If {\tt boltz\_calc\_also\_dos} is \verb#true#, the same $k$ mesh is used also for the DOS.
Overrides the \verb#kmesh# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_kmesh\_spacing]{\tt real(kind=dp) :: boltz\_kmesh\_spacing}
Overrides the \verb#kmesh_spacing# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_2d\_dir]{\tt  character(len=4) :: boltz\_2d\_dir}
\label{sec:boltz2ddir}
For two-dimensional systems, the direction along which the system is non-periodic. It can assume the following values: \texttt{x} for a 2D system on the $yz$ plane,  \texttt{y} for a 2D system on the $xz$ plane, \texttt{z} for a 2D system on the $xy$ plane, or \texttt{no} for a 3D system with periodicity along all threee directions.

This value is used when calculating the Seebeck coefficient, where the electrical conductivity tensor needs to be inverted. If the value is different from zero, only the relevant $2\times 2$ sub-block of the electrical conductivity is inverted.

The default value is \texttt{no}.

\subsection[boltz\_relax\_time]{\tt real(kind=dp) :: boltz\_relax\_time}
The relaxation time to be used for the calculation of the TDF and the transport coefficients.

The units are fs.
The default value is 10~fs.

\subsection[boltz\_mu\_min]{\tt real(kind=dp) :: boltz\_mu\_min}
Minimum value for the chemical potential $\mu$ for which we want to calculate the transport coefficients.

The units are eV.
No default value.

\subsection[boltz\_mu\_max]{\tt real(kind=dp) :: boltz\_mu\_max}
Maximum value for the chemical potential $\mu$ for which we want to calculate the transport coefficients.

The units are eV.
No default value.

\subsection[boltz\_mu\_step]{\tt real(kind=dp) :: boltz\_mu\_step}
Energy step for the grid of chemical potentials $\mu$ for which we want to calculate the transport coefficients.

The units are eV.
No default value.

\subsection[boltz\_temp\_min]{\tt real(kind=dp) :: boltz\_temp\_min}
Minimum value for the temperature $T$ for which we want to calculate the transport coefficients.

The units are K.
No default value.

\subsection[boltz\_temp\_max]{\tt real(kind=dp) :: boltz\_temp\_max}
Maximum value for the temperature $T$ for which we want to calculate the transport coefficients.

The units are K.
No default value.

\subsection[boltz\_temp\_step]{\tt real(kind=dp) :: boltz\_temp\_step}
Energy step for the grid of temperatures $T$ for which we want to calculate the transport coefficients.

The units are K.
No default value.

\subsection[boltz\_tdf\_energy\_step]{\tt real(kind=dp) :: boltz\_tdf\_energy\_step}
Energy step for the grid of energies for the TDF.

The units are eV.
The default value is 0.001~eV.

\subsection[boltz\_tdf\_smr\_type]{\tt character(len=120) :: boltz\_tdf\_smr\_type}
The type of smearing function to be used for the TDF. The available strings are the same of the global {\tt smr\_type} input flag. 

The default value is the one given via the {\tt smr\_type} input flag (if defined).

\subsection[boltz\_tdf\_smr\_fixed\_en\_width]{\tt real(kind=dp) :: boltz\_tdf\_smr\_fixed\_en\_width}
Energy width for the smearing function. Note that for the TDF, a standard (non-adaptive) smearing scheme is used.

The units are eV.
The default value is 0~eV. Note that if the width is smaller than twice the energy step {\tt boltz\_tdf\_energy\_step}, the TDF will be unsmeared (thus the default is to have an unsmeared TDF).

\subsection[boltz\_calc\_also\_dos]{\tt logical :: boltz\_calc\_also\_dos}
Whether to calculate also the DOS while calculating the TDF.

If one needs also the DOS, it is faster to calculate the DOS using
this flag instead of using independently the routines of the {\tt dos} module, since in this way the interpolation on the $k$ points will be performed only once.

The default value is \verb#false#.

\subsection[boltz\_dos\_energy\_min]{\tt real(kind=dp) :: boltz\_dos\_energy\_min}
The minimum value for the energy grid for the calculation of the DOS.

The units are eV.
The default value is {\tt minval(eigval)-0.6667}, where  {\tt minval(eigval)} i\
s the minimum eigenvalue returned by the ab-initio code on the ab-initio $q$ me\
sh.

\subsection[boltz\_dos\_energy\_max]{\tt real(kind=dp) :: boltz\_dos\_energy\_max}
The maximum value for the energy grid for the calculation of the DOS.

The units are eV.
The default value is {\tt maxval(eigval)+0.6667}, where  {\tt maxval(eigval)} i\
s the maximum eigenvalue returned by the ab-initio code on the ab-initio $q$ me\
sh.

\subsection[boltz\_dos\_energy\_step]{\tt real(kind=dp) :: boltz\_dos\_energy\_step}
Energy step for the grid of energies for the DOS.

The units are eV.
The default value is 0.001~eV.

\subsection[boltz\_dos\_smr\_type]{\tt character(len=120) :: boltz\_dos\_smr\_type}
Overrides the \verb#smr_type# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_dos\_adpt\_smr]{\tt logical :: boltz\_dos\_adpt\_smr}
Overrides the \verb#adpt_smr# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_dos\_adpt\_smr\_fac]{\tt real(kind=dp) :: boltz\_dos\_adpt\_smr\_fac}
Overrides the \verb#adpt_smr_fac# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_dos\_adpt\_smr\_max]{\tt real(kind=dp) :: boltz\_dos\_adpt\_smr\_max}
Overrides the \verb#adpt_smr_max# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_dos\_smr\_fixed\_en\_width]{\tt logical :: boltz\_dos\_smr\_fixed\_en\_width}
Overrides the \verb#smr_fixed_en_width# global variable (see
Sec.~\ref{sec:postw90-globalflags}).

\subsection[boltz\_bandshift]{\tt logical :: boltz\_bandshift}
Shift all conduction bands by a given amount (defined by {\tt boltz\_bandshift\_energyshift}).

Note: this flag slightly differs from the global {\tt scissors\_shift} flag: with {\tt boltz\_bandshift}, an exact rigid shift is applied \emph{after} interpolation; {\tt scissors\_shift} applies instead the shift \emph{before} interpolation. As a consequence, results may slightly differ (and this is why we provide both possibilities). Note also that with {\tt scissors\_shift} you have to provide the number of valence bands {\tt num\_valence\_bands}, while with {\tt boltz\_bandshift} you should provide the first band to shift {\tt boltz\_bandshift\_firstband} = {\tt num\_valence\_bands}$+1$.

The default value is \verb#false#.

\subsection[boltz\_bandshift\_firstband]{\tt integer :: boltz\_bandshift\_firstband}
Index of the first conduction band to shift.

That means that all bands with index $i\ge {\tt boltz\_bandshift\_firstband}$ will be shifted by  {\tt boltz\_bandshift\_energyshift}, if {\tt boltz\_bandshift} is \verb#true#.

The units are eV.
No default value; if {\tt boltz\_bandshift} is \verb#true#, this flag must be provided.

\subsection[boltz\_bandshift\_energyshift]{\tt real(kind=dp) :: boltz\_bandshift\_energyshift}
Energy shift of the conduction bands.

The units are eV.
No default value; if {\tt boltz\_bandshift} is \verb#true#, this flag must be provided.


\section{Generic Band Interpolation}
\subsection[boltzwann]{\tt logical :: geninterp}
Determines whether to enter the Generic Band Interpolation routines.

The default value is \verb#false#.

\subsection[geninterp\_alsofirstder]{\tt logical :: geninterp\_alsofirstder}
Whether to calculate also the first derivatives of the bands at the
given $k$ points.

The default value is \verb#false#.

\subsection[geninterp\_alsofirstder]{\tt logical :: geninterp\_single\_file}
Whether to write a single  {\tt seedname\_geninterp.dat} file (all I/O is done by the root node); or
instead multiple files (one for each node) with
names {\tt seedname\_geninterp\_NNNNN.dat}, where {\tt NNNNN} is the
node number.
See also the discussion in Sec.~\ref{sec:seedname.geninterp.dat} on
how to use this flag.

The default value is \verb#true#.
