From aaba0676c9f1a65cbb78aea9e2323f57a438050a Mon Sep 17 00:00:00 2001 From: yuhao Date: Wed, 14 Feb 2024 15:18:16 +0100 Subject: [PATCH 1/5] Add Section postw90/parameters --- docs/docs/user_guide/postw90/berry.md | 2 +- docs/docs/user_guide/postw90/boltzwann.md | 8 +- docs/docs/user_guide/postw90/geninterp.md | 3 +- docs/docs/user_guide/postw90/postw90params.md | 1713 +++++++++++++++++ docs/mkdocs.yml | 1 + 5 files changed, 1718 insertions(+), 9 deletions(-) create mode 100644 docs/docs/user_guide/postw90/postw90params.md diff --git a/docs/docs/user_guide/postw90/berry.md b/docs/docs/user_guide/postw90/berry.md index eb7f321f..c3190755 100644 --- a/docs/docs/user_guide/postw90/berry.md +++ b/docs/docs/user_guide/postw90/berry.md @@ -38,7 +38,7 @@ generalization of the Berry connection, $$ \begin{equation} -\label{eq_berry-connection-matrix} +\label{eq:berry-connection-matrix} {\bf A}_{nm}({\bf k})=\langle u_{n{\bf k}}\vert i\bm{\nabla}_{\bf k}\vert u_{m{\bf k}}\rangle={\bf A}_{mn}^*({\bf k}), \end{equation} diff --git a/docs/docs/user_guide/postw90/boltzwann.md b/docs/docs/user_guide/postw90/boltzwann.md index 2aad1221..7065b3b1 100644 --- a/docs/docs/user_guide/postw90/boltzwann.md +++ b/docs/docs/user_guide/postw90/boltzwann.md @@ -10,9 +10,7 @@ $\mathrm{\bm{S}}$ and the coefficient $\mathrm{\bm{K}}$ (defined below; it is the main ingredient of the thermal conductivity). The list of parameters of the `BoltzWann` module are summarized in - -Table [\[parameter_keywords_bw\]](#parameter_keywords_bw){reference-type="ref" -reference="parameter_keywords_bw"}. +Table [ `BoltzWann` Parameters](../postw90params/#boltzwann-parameters). An example of a Boltzmann transport calculation can be found in the `wannier90` Tutorial. @@ -21,9 +19,7 @@ calculation can be found in the `wannier90` Tutorial. material, with periodicity along all three spatial directions. If you are interested in studying 2D systems, set the correct value for the `boltz_2d_dir` variable - - (see Sec. [\[sec:boltz2ddir\]](#sec:boltz2ddir){reference-type="ref" - reference="sec:boltz2ddir"} for the documentation). + (see Sec. [boltz_2d_dir](../postw90params/#sec:boltz2ddir) for the documentation). This is important for the evaluation of the Seebeck coefficient. diff --git a/docs/docs/user_guide/postw90/geninterp.md b/docs/docs/user_guide/postw90/geninterp.md index d8240f11..84042324 100644 --- a/docs/docs/user_guide/postw90/geninterp.md +++ b/docs/docs/user_guide/postw90/geninterp.md @@ -8,8 +8,7 @@ points provided by the user. The list of parameters of the Generic Band Interpolation module are summarized in -Table [\[parameter_keywords_geninterp\]](#parameter_keywords_geninterp){reference-type="ref" -reference="parameter_keywords_geninterp"}. +Table [ `geninterp` Parameters](../postw90params/#geninterp-parameters). The list of input $k$ points for which the band have to be calculated is read from the file named `seedname_geninterp.kpt`. The format of this file is described below. diff --git a/docs/docs/user_guide/postw90/postw90params.md b/docs/docs/user_guide/postw90/postw90params.md new file mode 100644 index 00000000..b4b0fbb1 --- /dev/null +++ b/docs/docs/user_guide/postw90/postw90params.md @@ -0,0 +1,1713 @@ +Parameters +========== + +Introduction +------------ + +The `wannier90.x` code described in +Part [wannier90.x](../../wannier90/methodology/) calculates the maximally-localized Wannier +functions. + +The `postw90.x` executable contains instead a series of modules that +take the Wannier functions calculated by `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 +`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 `postw90.x` compiled with a +different compiler, refer to +Sec. [w90chk2chk](../../appendices/utilities/#w90chk2chkx) + in the Appendices for a description of how +to export/import this file. + +Usage +----- + +`postw90.x` can be run in parallel using MPI libraries to reduce the +computation time. + +For serial execution use: `postw90.x [seedname]` + +- `seedname`: If a seedname string is given the code will read its + input from a file `seedname.win`. The default value is `wannier`. + One can also equivalently provide the string `seedname.win` instead + of `seedname`. + +For parallel execution use: `mpirun -np NUMPROCS postw90.x [seedname]` + +- `NUMPROCS`: substitute with the number of processors that you want + to use. + +Note that the `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 `postw90.x` executable has been +compiled in its parallel version (follow the instructions in the file +`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. + +`seedname.win` File +------------------- + +The `postw90.x` uses the same `seedname.win` input file of +`wannier90.x`. The input keywords of `postw90.x` must thus be added to +this file, using the same syntax described in +Sec. [wannier90.x](../../wannier90/parameters/#seednamewin-file). + +Note that `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 `postw90.x`, so one can safely run `wannier90.x` on a file +that contains also `postw90.x` flags. + +Similarly, `postw90.x` ignores flags that refer only to `wannier90.x` +(as number of iterations, restart flags, ...). 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 *add* the `postw90` input +keywords to the `seedname.win` file that was used to obtain the Wannier +functions. + +List of available modules +------------------------- + + +The currently available modules in `postw90.x` are: + +- `dos`: Calculation of the density of states (DOS), projected density + of states (PDOS), net spin etc. + +- `kpath`: Calculation of $k$-space quantities such as energy bands, + Berry curvature and Berry curvature-like term of spin Hall + conductivity along a piecewise linear path in the BZ (see examples + 17, 18 and 29 of the tutorial). + +- `kslice`: Calculation of $k$-space quantities on a planar slice of + the BZ (see examples 17, 18 and 29 of the tutorial). + +- `berry`: Calculation of properties related to the BZ integral of the + Berry curvature, Berry connection and Berry curvature-like term of + spin Hall conductivity, including anomalous Hall conductivity, + orbital magnetisation, optical conductivity, nonlinear shift current + and spin Hall conductivity (see + Chap. [berry](../berry) and examples 18, 19, 25, 29 and 30 of the + tutorial). It also includes an option to compute $k\cdot p$ + expansion coefficients (see + Sec. [kdotp](../berry/#sec:kdotp) and example 33 of the tutorial). + +- `gyrotropic`: Calculation of gyrotropic properties, including + natural and current0induced optical rotation, and the + current-induced magnetization (see + Chap. [gyrotropic](../gyrotropic) and examples of the tutorial). + +- `BoltzWann`: Calculation of electronic transport properties for bulk + materials using the semiclassical Boltzmann transport equation (see + Chap. [ch:boltzwann](../boltzwann) and example 16 of the tutorial). + +- `geninterp` (Generic Band Interpolation): Calculation band energies + (and band derivatives) on a generic list of $k$ points (see + Chap. [ch:geninterp](../geninterp)). + +Keyword List +------------ + +On the next pages the list of available  input keywords is reported. In +particular, +Table [Global Parameters of `postw90`](#global-parameters-of-postw90){reference-type="ref" +reference="parameter_keywords_postw90"} reports keywords that affect the +generic behavior of all modules of . Often, these are "global" variables +that can be overridden by module-specific keywords (as for instance the +`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. [Global variables](#sec:postw90-globalflags); the description of the flags +specific to the modules can be found in the following sections. + +### Global Parameters of postw90 + +| Keyword | Type | Description | +| :---------------------------------:| :--: | :----------------------------------------------------------------------------------| +| kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | +| kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | +| adpt\_smr | L | Use adaptive smearing | +| adpt\_smr\_fac | R | Adaptive smearing prefactor | +| adpt\_smr\_max | P | Maximum allowed value for the adaptive energy smearing (eV) | +| smr\_type | S | Analytical form used for the broadened delta function | +| smr\_fixed\_en\_width | P | Energy smearing (if non-adaptive) | +| num\_elec\_per\_state | I | Number of electrons per state | +| scissors\_shift | P | Scissors shift applied to the conduction bands (eV) | +| num\_valence\_bands | I | Number of valence bands | +| spin\_decomp | L | Decompose various properties into up-spin, down-spin, and possibly spin-flip parts | +| spin\_axis\_polar | P | Polar angle of the spin quantization axis (deg) | +| spin\_axis\_azimuth | P | Azimuthal angle of the spin quantization axis (deg) | +| spin\_moment\(^*\) | L | Determines whether to evaluate the spin magnetic moment per cell | +| uHu\_formatted | L | Read a formatted `seedname.uHu` file | +| spn\_formatted | L | Read a formatted `seedname.spn` file | +| berry\_curv\_unit | S | Unit of Berry curvature | + + : ` seedname.win` file keywords controlling the general behaviour of + the modules in . 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 `spin_moment` does not affect the behavior of the modules + in , and does not really belong to any of them. It is listed here for + lack of a better place. +::: + +::: {#parameter_keywords_dos} + ----------------------- ------ ------------------------------------------------------------------------------- + Keyword Type Description + + + dos L Calculate the density of states and related properties + dos\_task S List of properties to compute + dos\_energy\_min P Lower limit of the energy range for computing the DOS (eV) + dos\_energy\_max P Upper limit of the energy range for computing the DOS (eV) + dos\_energy\_step R Step for increasing the energy in the specified range (eV) + dos\_project I List of WFs onto which the DOS is projected + kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) + kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ + adpt\_smr L Use adaptive smearing for the DOS + adpt\_smr\_fac R Adaptive smearing prefactor + adpt\_smr\_max P Maximum allowed value for the adaptive energy smearing (eV) + smr\_fixed\_en\_width P Energy smearing (if non-adaptive) for the DOS (eV) + smr\_type S Analytical form used for the broadened delta function when computing the DOS. + ----------------------- ------ ------------------------------------------------------------------------------- + + : ` seedname.win` file keywords controlling the `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. +::: + +::: {#parameter_keywords_kpath} + ---------------------- ------ -------------------------------------------------------------- + Keyword Type Description + + + kpath L Calculate properties along a piecewise linear path in the BZ + kpath\_task L List of properties to evaluate + kpath\_num\_points I Number of points in the first kpath segment + kpath\_bands\_colour S Property used to colour the energy bands along the path + ---------------------- ------ -------------------------------------------------------------- + + : ` seedname.win` file keywords controlling the `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. +::: + +::: {#parameter_keywords_kslice} + ------------------------------ ------ ------------------------------------------------------------------------------------- + Keyword Type Description + + + kslice L Calculate properties on a slice in the BZ + kslice\_task S List of properties to evaluate + kslice\_corner R Position of the corner of the slice + kslice\_b1 R First vector defining the slice + kslice\_b2 R Second vector defining the slice + kslice\_2dkmesh I Dimensions of the uniform interpolation $k$-mesh on the slice (one or two integers) + P + kslice\_fermi\_lines\_colour S Property used to colour the Fermi lines + ------------------------------ ------ ------------------------------------------------------------------------------------- + + : `seedname.win` file keywords controlling the `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. +::: + +::: {#parameter_keywords_berry} + ---------------------------------- ------ ----------------------------------------------------------------------------------------------------------------------------------------------- + Keyword Type Description + + + berry L Calculate Berry-type quantities + berry\_task S List of properties to compute + kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) + kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ + berry\_curv\_adpt\_kmesh I Linear dimension of the adaptively refined $k$-mesh used to compute the anomalous/spin Hall conductivity + berry\_curv\_adpt\_kmesh\_thresh P Threshold magnitude of the Berry curvature for adaptive refinement + kubo\_freq\_min P Lower limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV) + kubo\_freq\_max P Upper limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV) + kubo\_freq\_step R Step for increasing the optical frequency in the specified range + kubo\_eigval\_max P Maximum energy eigenvalue included when evaluating the Kubo-Greenwood conductivity, JDOS, shift current and spin Hall conductivity + adpt\_smr L Use adaptive energy smearing for the optical conductivity, JDOS, shift current and spin Hall conductivity + adpt\_smr\_fac R Adaptive smearing prefactor + adpt\_smr\_max P Maximum allowed value for the adaptive energy smearing (eV) + smr\_type S Analytical form used for the broadened delta function when computing the optical conductivity, JDOS, shift current and spin Hall conductivity + smr\_fixed\_en\_width P Energy smearing (if non-adaptive) for the optical conductivity, JDOS, shift current and spin Hall conductivity (eV) + sc\_eta R Energy broadening of energy differences in the sum over virtual states when computing shift current + sc\_phase\_conv I Convention for phase factor of Bloch states when computing shift current + sc\_w\_thr R Frequency threshold for speeding up delta function integration when computing shift current + sc\_use\_eta\_corr L Use finite-eta correction for computing shift current + shc\_freq\_scan L Calculate Fermi energy scan or frequency scan of spin Hall conductivity + shc\_method S How to obtain the spin current matrix elements for SHC + shc\_alpha I The spin current direction of spin Hall conductivity + shc\_beta I The direction of applied electrical field of spin Hall conductivity + shc\_gamma I The spin direction of the spin current of spin Hall conductivity + shc\_bandshift L Rigid bandshift of the conduction bands + shc\_bandshift\_firstband I Index of the first band to shift + shc\_bandshift\_energyshift P Energy shift of the conduction bands (eV) + kdotp\_kpoint R $k$ point for $k\cdot p$ expansion ($2\pi/a$, with $a$ lattice constant in Å) + kdotp\_num\_bands I Number of bands for $k\cdot p$ expansion + kdotp\_bands I Band indexes corresponding to the $k\cdot p$ bands + + ---------------------------------- ------ ----------------------------------------------------------------------------------------------------------------------------------------------- + + : ` seedname.win` file keywords controlling the `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. +::: + +::: {#parameter_keywords_gyrotropic} + --------------------------- ------ ------------------------------------------------------------------------------------------- + Keyword Type Description + + + gyrotropic L Calculate gyrotropic quantities + gyrotropic\_task L List of properties to compute + kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) + kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ + gyrotropic\_freq\_min P Lower limit of the frequency range for optical rotation (eV) + gyrotropic\_freq\_max P Upper limit of the frequency range for optical rotation (eV) + gyrotropic\_freq\_step P Step for increasing the optical frequency in the specified range + gyrotropic\_eigval\_max P Maximum energy eigenvalue included when evaluating the interband natural optical activity + gyrotropic\_degen\_thresh P threshold to exclude degenerate bands from the calculation + smr\_type S Analytical form used for the broadened delta function + smr\_fixed\_en\_width P Energy smearing (eV) + band\_list I list of bands used in the calculation + gyrotropic\_box\_center R + gyrotropic\_box\_b1 R + gyrotropic\_box\_b2 R + gyrotropic\_box\_b3 R + --------------------------- ------ ------------------------------------------------------------------------------------------- + + : ` seedname.win` file keywords controlling the `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. +::: + +::: {#parameter_keywords_bw} + ----------------------------------- ------ -------------------------------------------------------------------------- + Keyword Type Description + + + boltzwann L Calculate Boltzmann transport coefficients + kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) + kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ + boltz\_2d\_dir S Non-periodic direction (for 2D systems only) + boltz\_relax\_time P Relaxation time in fs + boltz\_mu\_min P Minimum value of the chemical potential $\mu$ in eV + boltz\_mu\_max P Maximum value of the chemical potential $\mu$ in eV + boltz\_mu\_step R Step for $\mu$ in eV + boltz\_temp\_min P Minimum value of the temperature $T$ in Kelvin + boltz\_temp\_max P Maximum value of the temperature $T$ in Kelvin + boltz\_temp\_step R Step for $T$ in Kelvin + boltz\_tdf\_energy\_step R Energy step for the TDF (eV) + boltz\_tdf\_smr\_fixed\_en\_width P Energy smearing for the TDF (eV) + boltz\_tdf\_smr\_type S Smearing type for the TDF + boltz\_calc\_also\_dos L Calculate also DOS while calculating the TDF + boltz\_dos\_energy\_min P Minimum value of the energy for the DOS in eV + boltz\_dos\_energy\_max P Maximum value of the energy for the DOS in eV + boltz\_dos\_energy\_step R Step for the DOS in eV + smr\_type S Smearing type for the DOS + adpt\_smr L Use adaptive smearing for the DOS + adpt\_smr\_fac R Adaptive smearing prefactor + adpt\_smr\_max P Maximum allowed value for the adaptive energy smearing (eV) + fixed\_en\_width P Energy smearing (if non-adaptive) for the DOS (eV) + boltz\_bandshift L Rigid bandshift of the conduction bands + boltz\_bandshift\_firstband I Index of the first band to shift + boltz\_bandshift\_energyshift P Energy shift of the conduction bands (eV) + ----------------------------------- ------ -------------------------------------------------------------------------- + + : `seedname.win` file keywords controlling the  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. +::: + +::: {#parameter_keywords_geninterp} + ------------------------- ------ --------------------------------------------- + Keyword Type Description + + + geninterp L Calculate bands for given set of $k$ points + geninterp\_alsofirstder L Calculate also first derivatives + geninterp\_single\_file L Write a single file or one for each process + ------------------------- ------ --------------------------------------------- + + : `seedname.win` file keywords controlling the Generic Band + Interpolation (`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. +::: + +Global variables {#sec:postw90-globalflags} +---------------- + +### `integer :: kmesh(:)` + +Dimensions of the interpolation grid used in `postw90.x`. + +*Not to be confused with the `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 `kmesh_spacing` or +` kmesh` must be defined. + +### `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 Å$^{-1}$. + +If you use a module which needs a k-mesh, either `kmesh_spacing` or +` kmesh` must be defined. + +### `logical :: adpt_smr` + +Determines whether to use an adaptive scheme for broadening the DOS and +similar quantities defined on the energy axis. If `true`, the values for +the smearing widths are controlled by the flag `adpt_smr_fac`. + +The default value is `true`. + +### `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 ` 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 `adpt_smr_max`, the latter value is used. + +The default value is $\sqrt{2}$. + +### `real(kind=dp) :: adpt_smr_max` + +See description given immediately above. + +The units are eV. The default value is 1.0. + +### `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. + +- `gauss`: Gaussian smearing + +- `m-pN`: derivative of the $N$-th order Methfessel-Paxton function + ($N\geq 0$). Example: `m-p2` for the second-order Methfessel-Paxton + function. If only `m-p` is provided, the first-order function is + used, i.e., it is equivalent to `m-p1`. + +- `m-v` or `cold`: derivative of the Marzari--Vanderbilt cold-smearing + function + +- `f-d`: derivative of the Fermi-Dirac distribution function + +The default value is `gauss`. + +### `logical :: smr_fixed_en_width` + +Energy width for the smearing function for the DOS. Used only if +` adpt_smr` is `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. `dos_energy_step` for the `dos` +module), the DOS will be unsmeared (thus the default is to have an +unsmeared properties when `adpt_smr` is set to `false`.). + +### `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 `spinors=true`, 2 otherwise. + +### `real(kind=dp) :: scissors_shift` + +Scissors shift applied to the conduction bands. + +**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 +`boltz_bandshift` instead. If you are calculating spin Hall +conductivity, consider using `shc_bandshift` instead. + +The units are eV. The default value is 0 eV (i.e., no scissors shift +applied). + +### `integer :: num_valence_bands` + +Number of valence bands of the system. Used in different modules and for +the scissors shift. + +No default value. + +### `logical :: spin_decomp` + +If `true`, extra columns are added to some output files (such as +`seedname-dos.dat` for the `dos` module, and analogously for the `berry` +and `BoltzWann` modules). + +For the `dos` and `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 `spin_axis_polar` and ` spin_axis_azimuth`). For +the `berry` module with ` berry_task = kubo`, three extra columns are +added to ` 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 `seedname-kubo*.dat` where the complex optical conductivity is +stored. + +The file `seedname.spn` must be present at input. Furthermore, if this +variable is set to `true` it requires `num_elec_per_state = 1`. + +The default value is `false`. + +### `real(kind=dp) :: spin_axis_polar` + +Polar angle of the spin quantization axis. + +The units are degrees. The default value is 0. + +### `real(kind=dp) :: spin_axis_azimuth` + +Azimuthal angle of the spin quantization axis. + +The units are degrees. The default value is 0. + +### `logical :: spin_moment` + +Determines whether to evaluate the spin moment. + +The default value is `false`. + +### `logical :: uHu_formatted` + +If `uHu_formatted`=`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 `false`. + +### `logical :: spn_formatted` + +If `spn_formatted`=`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 `false`. + +### `character(len=20) :: berry_curv_unit` + +Unit in which the Berry curvature is specified at input (in +` berry_curv_adpt_kmesh_thresh`) or written to file (when +` kpath_task=curv` or ` kpath_task=shc` or `kslice_task=curv` or +`kslice_task=shc`). + +- `ang2`: Angstrom$^2$ + +- `bohr2`: Bohr$^2$ (atomic units) + +The default value is `ang2`. + +### `real(kind=dp) :: sc_eta` + +The width $\eta$ used to broaden energy differences in denominators of +the form + +$$ +\begin{equation} +\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}. +\end{equation} +$$ + +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. + +### `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. [@pythtb]: + +- 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): + + $$ + \begin{equation} + |u_{n\bf{k}}\rangle = \sum_{\bf{R}} e^{-i{\bf k}({\bf r}-{\bf R}-{\bm \tau}_{n})}| w_{n\bf{R}} \rangle + \end{equation} + $$ + +- 2: Do not include Wannier centre in the phase factor (usual + `Wannier90` convention): + + $$ + \begin{equation} + |u_{n\bf{k}}\rangle = \sum_{\bf{R}} e^{-i\bf{k}(\bf{r}-\bf{R})}| w_{n\bf{R}} \rangle + \end{equation} + $$ + +If `sc_use_eta_corr=true`, 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. +[@ibanez-azpiroz_ab_2018]). If `sc_use_eta_corr=false`, the convention +can affect the full shift-current matrix element (see Ref. +[@Lihm_shift_eta_2021]). + +The default value is 1. + +### `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. + +### `logical :: sc_use_eta_corr` + +If `sc_use_eta_corr=true`, apply the finite-eta correction of the shift +current (Eq. (19) of Ref. [@Lihm_shift_eta_2021]). Without the +correction, the convention of the Bloch sum (determined by +`sc_phase_conv`) can affect the computed shift-current spectra. See Ref. +[@Lihm_shift_eta_2021] for details. + +The default value is `true`. + +DOS +--- + +Note that the behavior of the `dos` module is also influenced by the +value of some global flags (listed in +Table [Global Parameters of postw90](#global-parameters-of-postw90)), +as `spin_decomp`, +`spin_axis_polar`, `spin_axis_azimuth`, `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 `dos_`. + +### `logical :: dos` + +Determines whether to enter the DOS routines. + +The default value is `false`. + +### `character(len=20) :: dos_task` + +The quantity to compute when `dos=true` + +The valid options for this parameter are: + +- `dos_plot` Density of states. An output data file `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 + `spin_decomp=true` + +The default value is `dos_plot`. + +### `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 `seedname.eig`, minus 0.6667. + +### `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 `seedname.eig`, plus +0.6667. + +### `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. + +### `integer :: dos_project(:)` + +If present `postw90` computes, instead of the total DOS, the partial DOS +projected onto the WFs listed. The WFs are numbered according to the +file `seedname.wout`. + +For example, to project onto WFs 2, 6, 7, 8, and 12: + +`dos_project : 2, 6-8, 12` + +The DOS projected onto a set ${\cal S}$ of orbitals is calculated as + +$$ +\begin{equation} +\begin{aligned} +\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{aligned} +\end{equation} +$$ + +where $N_k$ is the number of mesh points used to sample the BZ, and the +superscript (H) and (W) refer to *Hamiltonian gauge* and *Wannier +gauge* [@wang-prb06]. + +### `integer :: dos_kmesh(:)` + +Overrides the `kmesh` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: dos_kmesh_spacing` + +Overrides the `kmesh_spacing` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: dos_adpt_smr` + +Overrides the `adpt_smr` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: dos_adpt_smr_fac` + +Overrides the `adpt_smr_fac` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: dos_adpt_smr_max` + +Overrides the `adpt_smr_max` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: dos_smr_fixed_en_width` + +Overrides the `smr_fixed_en_width` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +Note that if the width is smaller than twice the energy step +`dos_energy_step`, the DOS will be unsmeared (thus the default is to +have an unsmeared DOS). + +### `character(len=20) :: dos_smr_type` + +Overrides the `smr_type` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +kpath +----- + +### `logical :: kpath` + +Determines whether to enter the kpath routines. + +The default value is `false`. + +### `character(len=20) :: kpath_task` + +The quantities to plot when `kpath=true` + +The valid options for this parameter are: + +- `bands` Energy bands, in eV. The following files are created: + + - `seedname-bands.dat` (data file) + + - `seedname-bands.gnu` (`gnuplot` script) + + - `seedname-bands.py` (`python` script) + + - `seedname-path.kpt` (list of $k$-points along the path, written + in the `pwscf` format) + +- `curv` Minus the Berry curvature given by + [Berry Eq. (15)](../berry/#mjx-eqn:eq:ahc) of + Ch. [berry](../berry), in units of ` berry_curv_unit`. The following + files are created: + + - `seedname-curv.dat` (data file) + + - `seedname-curv_{x,y,z}.gnu` (`gnuplot` scripts) + + - `seedname-curv_{x,y,z}.py` (`python` scripts) + +- `morb` The integrand of the $k$-space orbital magnetization formula + \[[Berry Eq. (16)](../berry/#mjx-eqn:eq:morb) of + Ch. [berry](../berry)\] in eV$\cdot$Å$^2$. Four output files are + created: + + - `seedname-morb.dat` (data file) + + - `seedname-morb_{x,y,z}.gnu` (`gnuplot` scripts) + + - `seedname-morb_{x,y,z}.py` (`python` scripts) + +- `shc` The band-projected Berry curvature-like term of spin Hall + conductivity given by + [Berry Eq. (19)](../berry/#mjx-eqn:eq:kubo_shc_berry) of + Ch. [berry](../berry), in units of ` berry_curv_unit`. The following + files are created: + + - `seedname-shc.dat` (data file) + + - `seedname-shc.gnu` (`gnuplot` scripts) + + - `seedname-shc.py` (`python` scripts) + +- Any combination of the above. The following combinations are of + special interest + + `kpath_task = bands+curv` + + `kpath_task = bands+morb` + + `kpath_task = bands+shc` + + They generate the following files: + + - `seedname-bands.dat` (data file) + + - `seedname-{curv,morb,shc}.dat` (data file) + + - `seedname-bands+{curv,morb}_{x,y,z}.py` or + `seedname-bands+shc.py` (`python` scripts) + + 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, or $k$-resolved Berry + curvature-like term of spin Hall conductivity) in the bottom panel. + +The default value is `bands`. + +### `integer :: kpath_num_points` + +If `kpath`=`true`, then the number of points along the first +section of the bandstructure plot given by `kpoint_path`. Other sections +will have the same density of $k$-points. + +The default value is 100. + +### `character(len=20) :: kpath_bands_colour` + +When `kpath_task=bands`, colour code the energy bands according to the +specified quantity. + +The valid options for this parameter are: + +- `spin` Spin projection (in units of $\hbar/2$) along the + quantization axis defined by the variables ` spin_axis_polar` and + `spin_axis_azimuth`, for a spinor calculation + +- `shc` Band-projected Berry curvature-like term of spin Hall + conductivity (in units of + `berry_curv_unit`) defined by the variables ` shc_alpha`, `shc_beta` + and `shc_gamma`, for a spinor calculation + +- `none` no colour coding + +The default value is `none`. + +kslice +------ + +### `logical :: kslice` + +Determines whether to enter the kslice routines. + +The default value is `false`. + +### `character(len=20) :: kslice_task` + +The quantity to plot when `kslice=true` + +The valid options for this parameter are: + +- `fermi_lines` Lines of intersection between constant-energy surfaces + and the slice. The energy level is specified by the keyword + `fermi_energy`. Output files: + + - `seedname-kslice-fermi-spn.dat` (data file when + `kslice_fermi_lines_colour = spin`) + + - `seedname-bnd_n.dat` (`gnuplot` data files when + `kslice_fermi_lines_colour = none`) + + - `seedname-kslice-coord.dat` (`python` data files when + `kslice_fermi_lines_colour = none`) + + - `seedname-kslice-bands.dat` (`python` data file when + `kslice_fermi_lines_colour = none`) + + - `seedname-kslice-fermi_lines.gnu` (`gnuplot` script) + + - `seedname-kslice-fermi_lines.py` (`python` script) + +- `curv`\[+`fermi_lines`\] Heatmap of the Berry curvature of the + occupied states \[together with the constant-energy contours\]. The + unit of Berry curvature is `berry_curv_unit`. + + Output files: + + - `seedname-kslice-coord.dat` (data files) + + - `seedname-kslice-curv.dat` (data file) + + - `[seedname-kslice-bands.dat]` (data file) + + - `seedname-kslice-curv_{x,y,z}[+fermi_lines].py` (` python` + scripts) + +- `morb`\[+`fermi_lines`\] Heatmap of the $k$-space orbital + magnetization in eV$\cdot$Å$^2$ \[together with the constant-energy + contours\]. Output files: + + - `seedname-kslice-coord.dat` (data files) + + - `seedname-kslice-morb.dat` (data file) + + - `[seedname-kslice-bands.dat]` (data file) + + - `seedname-kslice-morb_{x,y,z}[+fermi_lines].py` (` python` + scripts) + +- `shc`\[+`fermi_lines`\] Heatmap of the Berry curvature-like term of + the occupied states \[together with the constant-energy contours\]. + The unit of Berry curvature-like term is `berry_curv_unit`. + + Output files: + + - `seedname-kslice-coord.dat` (data files) + + - `seedname-kslice-shc.dat` (data file) + + - `[seedname-kslice-bands.dat]` (data file) + + - `seedname-kslice-shc[+fermi_lines].py` (` python` scripts) + +The default value is `fermi_lines`. + +Note: When `kslice_fermi_lines_colour = none` the `gnuplot` scripts draw +the $k$-slices with a square shape, even when ` kslice_b1` and +`kslice_b2` below are not at right angles, or do not have equal lengths. +(The `python` scripts draw the slices with the correct parallelogram +shape.) + +### `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)$ + +### `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)$. + +### `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)$. + +### `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 `kslice_kmesh` is 50. + +### `character(len=20) :: kslice_fermi_lines_colour` + +When `kslice_task=fermi_lines` (but not when combined with ` curv` or +`morb`), colour code the Fermi lines according to the specified +quantity. + +The valid options for this parameter are: + +- `spin` Spin projection (in units of $\hbar/2$) along the + quantization axis defined by the variables ` spin_axis_polar` and + `spin_axis_azimuth`, for a spinor calculation + +- `none` no colour coding + +The default value is `none`. + +berry +----- + +### `logical :: berry` + +Determines whether to enter the berry routines. + +The default value is `false`. + +### `character(len=120) :: berry_task` + +The quantity to compute when `berry=true` + +The valid options for this parameter are: + +- `kubo` Complex optical conductivity and joint density of states. + Output files: + + - `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 `spin_decomp = true`. + + - `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 `spin_decomp = true`. + + - `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 `spin_decomp = true`. + +- `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: + + - `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 `fermi_energy_min` and + ` fermi_energy_max`. If a single Fermi energy is given, the AHC + is printed in `seedname.wpout` only. + +- `morb` Orbital magnetisation, in bohr magnetons per cell. + + Output files: + + - `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 `fermi_energy_min` and + ` fermi_energy_max`. If a single Fermi energy is given, ${\bf + M}^{\rm orb}$ is printed in `seedname.wpout` only. + +- `sc` Nonlinear shift current. Output files: + + - `seedname-sc_{xxx,xxy,xxz,...}.dat` (data files). The shift + current is described by a $3\times3\times3$ tensor + $\sigma^{abc}$. The program outputs a set of 18 files, and the 9 + remaining components can be obtained by taking into account that + $\sigma^{abc}$ is symmetric under $b\leftrightarrow c$ index + exchange. First column: optical frequency $\hbar\omega$ in eV. + Second column: nonlinear shift current + $\sigma^{abc}(\hbar\omega)$ in A/V$^{2}$. + +- `shc` Spin Hall conductivity (SHC), in $(\hbar/e)$S/cm. Output + files: + + - `seedname-shc-fermiscan.dat` (data file). The first column is + the number of entries in the list, the second column contains + the Fermi level $\varepsilon_F$ in eV, and the last column + contains the values of + $\sigma_{\alpha\beta}^{\text{spin}\gamma}(\varepsilon_F)$. This + file is written if a range of Fermi energies is specified via + `fermi_energy_min` and ` fermi_energy_max`. If a single Fermi + energy is given, the file will contain SHC at this specific + energy. + + - `seedname-shc-freqscan.dat` (data file). The first column is the + number of the entry in the list, the second column contains the + frequency $\hbar\omega$ in eV, and the following two columns + contain the values of the real part + $\Re[\sigma_{\alpha\beta}^{\text{spin}\gamma}(\omega)]$ and + imaginary part + $\Im[\sigma_{\alpha\beta}^{\text{spin}\gamma}(\omega)]$ of ac + SHC. This file is written if a range of frequencies is specified + via `kubo_freq_min` and ` kubo_freq_max`. + +- `kdotp` $k\cdot p$ expansion coefficients. Output files: + + - `seedname-kdotp_{0,1,2}.dat` (data files); respectively, the + zeroth, first and second order $k\cdot p$ expansion + coefficients, in units of eV, eV$\cdot$Å, and eV$\cdot$Å$^{2}$. + +There is no default value. + +### `integer :: berry_kmesh(:)` + +Overrides the `kmesh` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: berry_kmesh_spacing` + +Overrides the `kmesh_spacing` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `integer :: berry_curv_adpt_kmesh` + +If a positive integer $n$ is given and `berry_task=ahc`\[or +`berry_task=shc`\], an $n\times n\times n$ mesh is placed around points +on the uniform mesh (defined by either `berry_kmesh` or +`berry_kmesh_spacing`) where the magnitude of the $k$-space Berry +curvature\[$k$-space Berry curvature-like term of SHC\] exceeds the +threshold value specified in ` berry_curv_adpt_kmesh_thresh`. This can +be used to densify the BZ integration mesh around spikes in the Berry +curvature\[Berry curvature-like term of SHC\]. + +The default value is 1. + +### `real(kind=dp) :: berry_curv_adpt_kmesh_thresh` + +Magnitude of the Berry curvature\[Berry curvature-like term of SHC\] (in +units of `berry_curv_unit`) that triggers adaptive mesh refinement when +`berry_task=ahc`\[`berry_task=shc`\]. + +The default value is 100.0. + +### `real(kind=dp) :: kubo_freq_min` + +Lower limit of the frequency range for computing the optical +conductivity, JDOS and ac SHC. Units are eV. + +The default value 0.0. + +### `real(kind=dp) :: kubo_freq_max` + +Upper limit of the frequency range for computing the optical +conductivity, JDOS and ac SHC. Units are eV. + +If an inner energy window was specified, the default value is +` dis_froz_max`-`fermi_energy`+0.6667. Otherwise it is the difference +between the maximum and the minimum energy eigenvalue stored in +`seedname.eig`, plus 0.6667. + +### `real(kind=dp) :: kubo_freq_step` + +Difference between consecutive values of the optical frequency between +`kubo_freq_min` and `kubo_freq_max`. Units are eV. + +The default value is 0.01. + +### `real(kind=dp) :: kubo_eigval_max` + +Maximum energy eigenvalue of the eigenstates to be included in the +evaluation of the optical conductivity, JDOS and ac SHC. 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 `seedname.eig` plus 0.6667. + +### `logical :: kubo_adpt_smr` + +Overrides the `adpt_smr` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: kubo_adpt_smr_fac` + +Overrides the `adpt_smr_fac` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: kubo_adpt_smr_max` + +Overrides the `adpt_smr_max` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: kubo_smr_fixed_en_width` + +Overrides the `smr_fixed_en_width` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `character(len=120) :: kubo_smr_type` + +Overrides the `smr_type` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: shc_freq_scan` + +Determines whether to calculate the frequency scan (i.e. the ac SHC) or +the Fermi energy scan (i.e. the dc SHC) of the spin Hall conductivity. + +The default value is `false`, which means dc SHC is calculated. + +### `character(len=120) :: shc_method` + +If it is `qiao/ryoo`, the ac or dc SHC is calculated using Junfeng +Qiao's/Jihoon Ryoo's method. To calculate the Kubo formula, the spin +current matrix elements are required, and the two methods differ in the +degree of approximation. For details, see the section +[shc](../berry/#sec:shc). + +### `integer :: shc_alpha` + +The $\alpha$ index of spin Hall conductivity +$\sigma_{\alpha\beta}^{\text{spin}\gamma}$, i.e. the direction of spin +current. Possible values are `1`, `2` and `3`, representing the `x`, `y` +and `z` directions respectively. + +The default value is `1`. + +### `integer :: shc_beta` + +The $\beta$ index of spin Hall conductivity +$\sigma_{\alpha\beta}^{\text{spin}\gamma}$, i.e. the direction of +applied electric field. Possible values are `1`, `2` and `3`, +representing the `x`, `y` and `z` directions respectively. + +The default value is `2`. + +### `integer :: shc_gamma` + +The $\gamma$ index of spin Hall conductivity +$\sigma_{\alpha\beta}^{\text{spin}\gamma}$, i.e. the spin direction of +spin current. Possible values are `1`, `2` and `3`, representing the +`x`, `y` and `z` directions respectively. + +The default value is `3`. + +If all the `shc_alpha`, `shc_beta` and `shc_gamma` are set as default +values, the $\sigma_{xy}^{\text{spin}z}$ is computed. + +### `logical :: shc_bandshift` + +Shift all conduction bands by a given amount (defined by +`shc_bandshift_energyshift`). + +Note: this flag slightly differs from the global `scissors_shift` flag: +with `shc_bandshift`, an exact rigid shift is applied *after* +interpolation; `scissors_shift` applies instead the shift *before* +interpolation. As a consequence, results may slightly differ (and this +is why we provide both possibilities). Note also that with +`scissors_shift` you have to provide the number of valence bands +`num_valence_bands`, while with `shc_bandshift` you should provide the +first band to shift `shc_bandshift_firstband` = `num_valence_bands`$+1$. + +The default value is `false`. + +### `integer :: shc_bandshift_firstband` + +Index of the first conduction band to shift. + +That means that all bands with index +$i\ge {\tt shc\_bandshift\_firstband}$ will be shifted by +`shc_bandshift_energyshift`, if `shc_bandshift` is `true`. + +The units are eV. No default value; if `shc_bandshift` is `true`, this +flag must be provided. + +### `real(kind=dp) :: shc_bandshift_energyshift` + +Energy shift of the conduction bands. + +The units are eV. No default value; if `shc_bandshift` is `true`, this +flag must be provided. + +### `real(kind=dp) :: sc_eta` + +The width $\eta$ used to broaden energy differences in denominators of +the form + +$$ +\begin{equation} +\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}. +\end{equation} +$$ + +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. + +### `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. [@pythtb]: + +- 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): + + $$ + \begin{equation} + |u_{n\bf{k}}\rangle = \sum_{\bf{R}} e^{-i{\bf k}({\bf r}-{\bf R}-{\bm \tau}_{n})}| w_{n\bf{R}} \rangle + \end{equation} + $$ + +- 2: Do not include Wannier centre in the phase factor (usual + `Wannier90` convention): + + $$ + \begin{equation} + |u_{n\bf{k}}\rangle = \sum_{\bf{R}} e^{-i\bf{k}(\bf{r}-\bf{R})}| w_{n\bf{R}} \rangle + \end{equation} + $$ + +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. [@ibanez-azpiroz_ab_2018]). + +The default value is 1. + +### `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. + +### `real(kind=dp) :: kdotp_kpoint(3)` + +Defines the $k$ point around which the $k\cdot p$ expansion is +performed. + +The default value is 0.0 0.0 0.0 ($\Gamma$). + +### `integer :: kdotp_num_bands` + +Number of bands forming the $k\cdot p$ basis set. + +No default value. + +### `integer :: kdotp_bands(kdotp_num_bands)` + +Band indexes of bands belonging to $k\cdot p$ basis. Number of entries +must be equal to the integer defined in `kdotp_num_bands`. The band +labelling follows that of "wannierised" bands. + +No default value. + +Gyrotropic +---------- + +### `logical :: gyrotropic` + +Determines whether to enter the gyrotropic routines. + +The default value is `false`. + +### `character(len=120) :: gyrotropic_task` + +The quantity to compute when `gyrotropic=true` + +May contain one or more of the following valid options (note that each +option starts with a '-'): + +- `-D0` The Berry-curvature dipole tensor (dimensionless) + + Output file: `seedname-gyrotropic-D.dat` ( see Sec. + [output data format](#output-data-format) for file format description) + +- `-Dw` The finite-frequency Berry-curvature dipole tensor + (dimensionless) + + Output file: `seedname-gyrotropic-tildeD.dat` ( see Sec. + [output data format](#output-data-format) for file format description) + +- `-C` The ohmic conductivity tensor (Ampere/cm) + + Output file: `seedname-gyrotropic-C.dat` ( see Sec. + [output data format](#output-data-format) for file format description) + +- `-K` The orbital contribution to the kME tensor (Ampere) + + Output file: `seedname-gyrotropic-K_orb.dat` ( see Sec. + [output data format](#output-data-format) for file format description) + + - `-spin` : if this task is present, compute also the spin + contribution. + + Output file: `seedname-gyrotropic-K_spin.dat` + +- `-NOA` The orbital contribution to the NOA (Å) + + Output file: `seedname-gyrotropic-NOA_orb.dat` ( see Sec. + [output data format](#output-data-format) for file format description) + + - `-spin` : if this task is present, compute also the spin + contribution. + + Output file: `seedname-gyrotropic-NOA_spin.dat` + +- `-dos` the density of states + + Output file: + `seedname-gyrotropic-DOS.dat`. First column - energy (eV), second + column - DOS ($1/(\mathrm{eV}\times\mathring{A}^3)$) + +There is no default value. + +### output data 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$ + +### `integer :: gyrotropic_kmesh(:)` + +Overrides the `kmesh` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: gyrotropic_kmesh_spacing` + +Overrides the `kmesh_spacing` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `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. + +### `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 +` dis_froz_max`-`fermi_energy`+0.6667. Otherwise it is the difference +between the maximum and the minimum energy eigenvalue stored in +`seedname.eig`, plus 0.6667. + +### `real(kind=dp) :: gyrotropic_freq_step` + +Difference between consecutive values of the optical frequency between +`gyrotropic_freq_min` and `gyrotropic_freq_max`. + +Units are eV. The default value is 0.01. + +### `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 `seedname.eig` plus 0.6667. + +### `logical :: gyrotropic_smr_fixed_en_width` + +Overrides the `smr_fixed_en_width` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `character(len=120) :: gyrotropic_smr_type` + +Overrides the `smr_type` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `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. + +### `character(len=120) :: gyrotropic_box_center` + +\- three real numbers. Optionally the integration may be restricted to a +parallelogram, centered at `gyrotropic_box_center` and defined by +vectors `gyrotropic_box_b{1,2,3}` + +In reduced coordinates. Default value is 0.5 0.5 0.5 + +### `character(len=120) :: gyrotropic_box_b1` + +\- three real numbers. In reduced coordinates. Default value is 1.0 0.0 +0.0 + +### `character(len=120) :: gyrotropic_box_b2` + +\- three real numbers. In reduced coordinates. Default value is 0.0 1.0 +0.0 + +### `character(len=120) :: gyrotropic_box_b3` + +\- three real numbers. In reduced coordinates. Default value is 0.0 0.0 +1.0 + +BoltzWann +--------- + +### `logical :: boltzwann` + +Determines whether to enter the  routines. + +The default value is `false`. + +### `integer :: boltz_kmesh(:)` + +It determines the interpolation $k$ mesh used to calculate the TDF (from +which the transport coefficient are calculated). If +`boltz_calc_also_dos` is `true`, the same $k$ mesh is used also for the +DOS. Overrides the `kmesh` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: boltz_kmesh_spacing` + +Overrides the `kmesh_spacing` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `character(len=4) :: boltz_2d_dir` {#sec:boltz2ddir} + +For two-dimensional systems, the direction along which the system is +non-periodic. It can assume the following values: `x` for a 2D system on +the $yz$ plane, `y` for a 2D system on the $xz$ plane, `z` for a 2D +system on the $xy$ plane, or `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 `no`. + +### `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. + +### `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. + +### `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. + +### `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. + +### `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. + +### `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. + +### `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. + +### `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. + +### `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 `smr_type` input flag. + +The default value is the one given via the `smr_type` input flag (if +defined). + +### `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 `boltz_tdf_energy_step`, the TDF will +be unsmeared (thus the default is to have an unsmeared TDF). + +### `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 `dos` module, +since in this way the interpolation on the $k$ points will be performed +only once. + +The default value is `false`. + +### `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 `minval(eigval)-0.6667`, where +`minval(eigval)` i s the minimum eigenvalue returned by the ab-initio +code on the ab-initio $q$ me sh. + +### `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 `maxval(eigval)+0.6667`, where +`maxval(eigval)` i s the maximum eigenvalue returned by the ab-initio +code on the ab-initio $q$ me sh. + +### `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. + +### `character(len=120) :: boltz_dos_smr_type` + +Overrides the `smr_type` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: boltz_dos_adpt_smr` + +Overrides the `adpt_smr` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: boltz_dos_adpt_smr_fac` + +Overrides the `adpt_smr_fac` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `real(kind=dp) :: boltz_dos_adpt_smr_max` + +Overrides the `adpt_smr_max` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: boltz_dos_smr_fixed_en_width` + +Overrides the `smr_fixed_en_width` global variable (see +Sec. [Global variables](#sec:postw90-globalflags)). + +### `logical :: boltz_bandshift` + +Shift all conduction bands by a given amount (defined by +`boltz_bandshift_energyshift`). + +Note: this flag slightly differs from the global `scissors_shift` flag: +with `boltz_bandshift`, an exact rigid shift is applied *after* +interpolation; `scissors_shift` applies instead the shift *before* +interpolation. As a consequence, results may slightly differ (and this +is why we provide both possibilities). Note also that with +`scissors_shift` you have to provide the number of valence bands +`num_valence_bands`, while with `boltz_bandshift` you should provide the +first band to shift `boltz_bandshift_firstband` = +`num_valence_bands`$+1$. + +The default value is `false`. + +### `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 +`boltz_bandshift_energyshift`, if `boltz_bandshift` is `true`. + +The units are eV. No default value; if `boltz_bandshift` is `true`, this +flag must be provided. + +### `real(kind=dp) :: boltz_bandshift_energyshift` + +Energy shift of the conduction bands. + +The units are eV. No default value; if `boltz_bandshift` is `true`, this +flag must be provided. + +Generic Band Interpolation +-------------------------- + +### `logical :: geninterp` + +Determines whether to enter the Generic Band Interpolation routines. + +The default value is `false`. + +### `logical :: geninterp_alsofirstder` + +Whether to calculate also the first derivatives of the bands at the +given $k$ points. + +The default value is `false`. + +### `logical :: geninterp_single_file` + +Whether to write a single `seedname_geninterp.dat` file (all I/O is done +by the root node); or instead multiple files (one for each node) with +names `seedname_geninterp_NNNNN.dat`, where `NNNNN` is the node number. +See also the discussion in +Sec. [`seedname_geninterp.dat` or `seedname_geninterp_NNNNN.dat`](../geninterp/#sec:seedname.geninterp.dat). + +The default value is `true`. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 0039e111..2a0f2d10 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -27,6 +27,7 @@ nav: - "Notes on interpolations": "user_guide/wannier90/notes_interpolations.md" - "Sample inputs": "user_guide/wannier90/sample_inputs.md" - 'postw90.x': + - "Parameters": "user_guide/postw90/postw90params.md" - "Berry": "user_guide/postw90/berry.md" - "Gyrotropic": "user_guide/postw90/gyrotropic.md" - "BoltzWann": "user_guide/postw90/boltzwann.md" From 7eb04b2aa4cd4fab15e63b082c9951f1f544a0e6 Mon Sep 17 00:00:00 2001 From: npaulish Date: Wed, 14 Feb 2024 17:49:37 +0100 Subject: [PATCH 2/5] Fix tables in postw90/parameters.md file Fix a reference in postw90params.md --- docs/docs/user_guide/postw90/postw90params.md | 374 ++++++++---------- 1 file changed, 168 insertions(+), 206 deletions(-) diff --git a/docs/docs/user_guide/postw90/postw90params.md b/docs/docs/user_guide/postw90/postw90params.md index b4b0fbb1..4d783941 100644 --- a/docs/docs/user_guide/postw90/postw90params.md +++ b/docs/docs/user_guide/postw90/postw90params.md @@ -116,8 +116,7 @@ Keyword List On the next pages the list of available  input keywords is reported. In particular, -Table [Global Parameters of `postw90`](#global-parameters-of-postw90){reference-type="ref" -reference="parameter_keywords_postw90"} reports keywords that affect the +Table [Global Parameters of `postw90`](#global-parameters-of-postw90) reports keywords that affect the generic behavior of all modules of . Often, these are "global" variables that can be overridden by module-specific keywords (as for instance the `kmesh` flag). The subsequent tables describe the input parameters for @@ -126,228 +125,191 @@ A description of the behaviour of the global flags is described Sec. [Global variables](#sec:postw90-globalflags); the description of the flags specific to the modules can be found in the following sections. -### Global Parameters of postw90 +### Global Parameters of `postw90` | Keyword | Type | Description | | :---------------------------------:| :--: | :----------------------------------------------------------------------------------| -| kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | -| kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | -| adpt\_smr | L | Use adaptive smearing | -| adpt\_smr\_fac | R | Adaptive smearing prefactor | -| adpt\_smr\_max | P | Maximum allowed value for the adaptive energy smearing (eV) | -| smr\_type | S | Analytical form used for the broadened delta function | -| smr\_fixed\_en\_width | P | Energy smearing (if non-adaptive) | -| num\_elec\_per\_state | I | Number of electrons per state | -| scissors\_shift | P | Scissors shift applied to the conduction bands (eV) | -| num\_valence\_bands | I | Number of valence bands | -| spin\_decomp | L | Decompose various properties into up-spin, down-spin, and possibly spin-flip parts | -| spin\_axis\_polar | P | Polar angle of the spin quantization axis (deg) | -| spin\_axis\_azimuth | P | Azimuthal angle of the spin quantization axis (deg) | -| spin\_moment\(^*\) | L | Determines whether to evaluate the spin magnetic moment per cell | -| uHu\_formatted | L | Read a formatted `seedname.uHu` file | -| spn\_formatted | L | Read a formatted `seedname.spn` file | -| berry\_curv\_unit | S | Unit of Berry curvature | - - : ` seedname.win` file keywords controlling the general behaviour of - the modules in . Argument types are represented by, I for a integer, R +| kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | +| kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | +| adpt\_smr | L | Use adaptive smearing | +| adpt\_smr\_fac | R | Adaptive smearing prefactor | +| adpt\_smr\_max | P | Maximum allowed value for the adaptive energy smearing (eV) | +| smr\_type | S | Analytical form used for the broadened delta function | +| smr\_fixed\_en\_width | P | Energy smearing (if non-adaptive) | +| num\_elec\_per\_state | I | Number of electrons per state | +| scissors\_shift | P | Scissors shift applied to the conduction bands (eV) (deprecated) | +| num\_valence\_bands | I | Number of valence bands | +| spin\_decomp | L | Decompose various properties into up-spin, down-spin, and possibly spin-flip parts | +| spin\_axis\_polar | P | Polar angle of the spin quantization axis (deg) | +| spin\_axis\_azimuth | P | Azimuthal angle of the spin quantization axis (deg) | +| spin\_moment\(^*\) | L | Determines whether to evaluate the spin magnetic moment per cell | +| uHu\_formatted | L | Read a formatted `seedname.uHu` file | +| spn\_formatted | L | Read a formatted `seedname.spn` file | +| berry\_curv\_unit | S | Unit of Berry curvature | + +` seedname.win` file keywords controlling the general behaviour of + the modules in `postw90`. 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 `spin_moment` does not affect the behavior of the modules + for a text string. + \* The keyword `spin_moment` does not affect the behavior of the modules in , and does not really belong to any of them. It is listed here for lack of a better place. -::: - -::: {#parameter_keywords_dos} - ----------------------- ------ ------------------------------------------------------------------------------- - Keyword Type Description - - - dos L Calculate the density of states and related properties - dos\_task S List of properties to compute - dos\_energy\_min P Lower limit of the energy range for computing the DOS (eV) - dos\_energy\_max P Upper limit of the energy range for computing the DOS (eV) - dos\_energy\_step R Step for increasing the energy in the specified range (eV) - dos\_project I List of WFs onto which the DOS is projected - kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) - kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ - adpt\_smr L Use adaptive smearing for the DOS - adpt\_smr\_fac R Adaptive smearing prefactor - adpt\_smr\_max P Maximum allowed value for the adaptive energy smearing (eV) - smr\_fixed\_en\_width P Energy smearing (if non-adaptive) for the DOS (eV) - smr\_type S Analytical form used for the broadened delta function when computing the DOS. - ----------------------- ------ ------------------------------------------------------------------------------- - - : ` seedname.win` file keywords controlling the `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. -::: - -::: {#parameter_keywords_kpath} - ---------------------- ------ -------------------------------------------------------------- - Keyword Type Description - - - kpath L Calculate properties along a piecewise linear path in the BZ - kpath\_task L List of properties to evaluate - kpath\_num\_points I Number of points in the first kpath segment - kpath\_bands\_colour S Property used to colour the energy bands along the path - ---------------------- ------ -------------------------------------------------------------- - - : ` seedname.win` file keywords controlling the `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. -::: - -::: {#parameter_keywords_kslice} - ------------------------------ ------ ------------------------------------------------------------------------------------- - Keyword Type Description - - - kslice L Calculate properties on a slice in the BZ - kslice\_task S List of properties to evaluate - kslice\_corner R Position of the corner of the slice - kslice\_b1 R First vector defining the slice - kslice\_b2 R Second vector defining the slice - kslice\_2dkmesh I Dimensions of the uniform interpolation $k$-mesh on the slice (one or two integers) - P - kslice\_fermi\_lines\_colour S Property used to colour the Fermi lines - ------------------------------ ------ ------------------------------------------------------------------------------------- - - : `seedname.win` file keywords controlling the `kslice` module. + +### `berry` Parameters +| Keyword | Type | Description | +| :-------------------------------------------: | :--: | :-------------------------------------------------------------------------------------------------------------------------------------------- | +| berry | L | Calculate Berry-type quantities | +| berry\_task | S | List of properties to compute | +| \[berry\_\]kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | +| \[berry\_\]kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | +| berry\_curv\_adpt\_kmesh | I | Linear dimension of the adaptively refined \(k\)-mesh used to compute the anomalous/spin Hall conductivity | +| berry\_curv\_adpt\_kmesh\_thresh | P | Threshold magnitude of the Berry curvature for adaptive refinement | +| kubo\_freq\_min | P | Lower limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV) | +| kubo\_freq\_max | P | Upper limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV) | +| kubo\_freq\_step | R | Step for increasing the optical frequency in the specified range | +| kubo\_eigval\_max | P | Maximum energy eigenvalue included when evaluating the Kubo-Greenwood conductivity, JDOS, shift current and spin Hall conductivity | +| \[kubo\_\]adpt\_smr | L | Use adaptive energy smearing for the optical conductivity, JDOS, shift current and spin Hall conductivity | +| \[kubo\_\]adpt\_smr\_fac | R | Adaptive smearing prefactor | +| \[kubo\_\]adpt\_smr\_max | P | Maximum allowed value for the adaptive energy smearing (eV) | +| \[kubo\_\]smr\_type | S | Analytical form used for the broadened delta function when computing the optical conductivity, JDOS, shift current and spin Hall conductivity | +| \[kubo\_\]smr\_fixed\_en\_width | P | Energy smearing (if non-adaptive) for the optical conductivity, JDOS, shift current and spin Hall conductivity (eV) | +| sc\_eta | R | Energy broadening of energy differences in the sum over virtual states when computing shift current | +| sc\_phase\_conv | I | Convention for phase factor of Bloch states when computing shift current | +| sc\_w\_thr | R | Frequency threshold for speeding up delta function integration when computing shift current | +| sc\_use\_eta\_corr | L | Use finite-eta correction for computing shift current | +| shc\_freq\_scan | L | Calculate Fermi energy scan or frequency scan of spin Hall conductivity | +| shc\_method | S | How to obtain the spin current matrix elements for SHC | +| shc\_alpha | I | The spin current direction of spin Hall conductivity | +| shc\_beta | I | The direction of applied electrical field of spin Hall conductivity | +| shc\_gamma | I | The spin direction of the spin current of spin Hall conductivity | +| shc\_bandshift | L | Rigid bandshift of the conduction bands | +| shc\_bandshift\_firstband | I | Index of the first band to shift | +| shc\_bandshift\_energyshift | P | Energy shift of the conduction bands (eV) | +| kdotp\_kpoint | R | \(k\) point for \(k\cdot p\) expansion (\(2\pi/a\), with \(a\) lattice constant in Å) | +| kdotp\_num\_bands | I | Number of bands for \(k\cdot p\) expansion | +| kdotp\_bands | I | Band indexes corresponding to the \(k\cdot p\) bands | +| | | | + +` seedname.win` file keywords controlling the `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. -::: - -::: {#parameter_keywords_berry} - ---------------------------------- ------ ----------------------------------------------------------------------------------------------------------------------------------------------- - Keyword Type Description - - - berry L Calculate Berry-type quantities - berry\_task S List of properties to compute - kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) - kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ - berry\_curv\_adpt\_kmesh I Linear dimension of the adaptively refined $k$-mesh used to compute the anomalous/spin Hall conductivity - berry\_curv\_adpt\_kmesh\_thresh P Threshold magnitude of the Berry curvature for adaptive refinement - kubo\_freq\_min P Lower limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV) - kubo\_freq\_max P Upper limit of the frequency range for optical spectra, JDOS, shift current and spin Hall conductivity (eV) - kubo\_freq\_step R Step for increasing the optical frequency in the specified range - kubo\_eigval\_max P Maximum energy eigenvalue included when evaluating the Kubo-Greenwood conductivity, JDOS, shift current and spin Hall conductivity - adpt\_smr L Use adaptive energy smearing for the optical conductivity, JDOS, shift current and spin Hall conductivity - adpt\_smr\_fac R Adaptive smearing prefactor - adpt\_smr\_max P Maximum allowed value for the adaptive energy smearing (eV) - smr\_type S Analytical form used for the broadened delta function when computing the optical conductivity, JDOS, shift current and spin Hall conductivity - smr\_fixed\_en\_width P Energy smearing (if non-adaptive) for the optical conductivity, JDOS, shift current and spin Hall conductivity (eV) - sc\_eta R Energy broadening of energy differences in the sum over virtual states when computing shift current - sc\_phase\_conv I Convention for phase factor of Bloch states when computing shift current - sc\_w\_thr R Frequency threshold for speeding up delta function integration when computing shift current - sc\_use\_eta\_corr L Use finite-eta correction for computing shift current - shc\_freq\_scan L Calculate Fermi energy scan or frequency scan of spin Hall conductivity - shc\_method S How to obtain the spin current matrix elements for SHC - shc\_alpha I The spin current direction of spin Hall conductivity - shc\_beta I The direction of applied electrical field of spin Hall conductivity - shc\_gamma I The spin direction of the spin current of spin Hall conductivity - shc\_bandshift L Rigid bandshift of the conduction bands - shc\_bandshift\_firstband I Index of the first band to shift - shc\_bandshift\_energyshift P Energy shift of the conduction bands (eV) - kdotp\_kpoint R $k$ point for $k\cdot p$ expansion ($2\pi/a$, with $a$ lattice constant in Å) - kdotp\_num\_bands I Number of bands for $k\cdot p$ expansion - kdotp\_bands I Band indexes corresponding to the $k\cdot p$ bands - - ---------------------------------- ------ ----------------------------------------------------------------------------------------------------------------------------------------------- - - : ` seedname.win` file keywords controlling the `berry` module. + +### `dos` Parameters + +| Keyword | Type | Description | +| :--------------------------------: | :--: | :---------------------------------------------------------------------------- | +| dos | L | Calculate the density of states and related properties | +| dos\_task | S | List of properties to compute | +| dos\_energy\_min | P | Lower limit of the energy range for computing the DOS (eV) | +| dos\_energy\_max | P | Upper limit of the energy range for computing the DOS (eV) | +| dos\_energy\_step | R | Step for increasing the energy in the specified range (eV) | +| dos\_project | I | List of WFs onto which the DOS is projected | +| \[dos\_\]kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | +| \[dos\_\]kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | +| \[dos\_\]adpt\_smr | L | Use adaptive smearing for the DOS | +| \[dos\_\]adpt\_smr\_fac | R | Adaptive smearing prefactor | +| \[dos\_\]adpt\_smr\_max | P | Maximum allowed value for the adaptive energy smearing (eV) | +| \[dos\_\]smr\_fixed\_en\_width | P | Energy smearing (if non-adaptive) for the DOS (eV) | +| \[dos\_\]smr\_type | S | Analytical form used for the broadened delta function when computing the DOS. | + +` seedname.win ` file keywords controlling the `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. + +### `kpath` Parameters + +| Keyword | Type | Description | +| :-------------------------------: | :--: | :----------------------------------------------------------- | +| kpath | L | Calculate properties along a piecewise linear path in the BZ | +| kpath\_task | L | List of properties to evaluate | +| kpath\_num\_points | I | Number of points in the first kpath segment | +| kpath\_bands\_colour | S | Property used to colour the energy bands along the path | + +` seedname.win` file keywords controlling the `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. -::: - -::: {#parameter_keywords_gyrotropic} - --------------------------- ------ ------------------------------------------------------------------------------------------- - Keyword Type Description - - - gyrotropic L Calculate gyrotropic quantities - gyrotropic\_task L List of properties to compute - kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) - kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ - gyrotropic\_freq\_min P Lower limit of the frequency range for optical rotation (eV) - gyrotropic\_freq\_max P Upper limit of the frequency range for optical rotation (eV) - gyrotropic\_freq\_step P Step for increasing the optical frequency in the specified range - gyrotropic\_eigval\_max P Maximum energy eigenvalue included when evaluating the interband natural optical activity - gyrotropic\_degen\_thresh P threshold to exclude degenerate bands from the calculation - smr\_type S Analytical form used for the broadened delta function - smr\_fixed\_en\_width P Energy smearing (eV) - band\_list I list of bands used in the calculation - gyrotropic\_box\_center R - gyrotropic\_box\_b1 R - gyrotropic\_box\_b2 R - gyrotropic\_box\_b3 R - --------------------------- ------ ------------------------------------------------------------------------------------------- - - : ` seedname.win` file keywords controlling the `gyrotropic` module. + +### `kslice` Parameters +| Keyword | Type | Description | +| :---------------------------------------: | :--: | :------------------------------------------------------------------------------------ | +| kslice | L | Calculate properties on a slice in the BZ | +| kslice\_task | S | List of properties to evaluate | +| kslice\_corner | R | Position of the corner of the slice | +| kslice\_b1 | R | First vector defining the slice | +| kslice\_b2 | R | Second vector defining the slice | +| kslice\_2dkmesh | I | Dimensions of the uniform interpolation \(k\)-mesh on the slice (one or two integers) | +| kslice\_fermi\_level | P | This parameter is not used anymore. Use fermi_energy instead. | +| kslice\_fermi\_lines\_colour | S | Property used to colour the Fermi lines | + +`seedname.win` file keywords controlling the `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. + +### `gyrotropic` Parameters + +| Keyword | Type | Description | +| :------------------------------------: | :--: | :---------------------------------------------------------------------------------------- | +| gyrotropic | L | Calculate gyrotropic quantities | +| gyrotropic\_task | L | List of properties to compute | +| \[gyrotropic\_\]kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | +| \[gyrotropic\_\]kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | +| gyrotropic\_freq\_min | P | Lower limit of the frequency range for optical rotation (eV) | +| gyrotropic\_freq\_max | P | Upper limit of the frequency range for optical rotation (eV) | +| gyrotropic\_freq\_step | P | Step for increasing the optical frequency in the specified range | +| gyrotropic\_eigval\_max | P | Maximum energy eigenvalue included when evaluating the interband natural optical activity | +| gyrotropic\_degen\_thresh | P | threshold to exclude degenerate bands from the calculation | +| \[gyrotropic\_\]smr\_type | S | Analytical form used for the broadened delta function | +| \[gyrotropic\_\]smr\_fixed\_en\_width | P | Energy smearing (eV) | +| \[gyrotropic\_\]band\_list | I | list of bands used in the calculation | + gyrotropic\_box\_center
gyrotropic\_box\_b1
gyrotropic\_box\_b2
gyrotropic\_box\_b3 | R
R
R
R | The center and three basis vectors, defining the box for integration (in reduced coordinates, three real numbers for each vector) | + +` seedname.win` file keywords controlling the `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. -::: - -::: {#parameter_keywords_bw} - ----------------------------------- ------ -------------------------------------------------------------------------- - Keyword Type Description - - - boltzwann L Calculate Boltzmann transport coefficients - kmesh I Dimensions of the uniform interpolation $k$-mesh (one or three integers) - kmesh\_spacing R Minimum spacing between $k$ points in Å$^{-1}$ - boltz\_2d\_dir S Non-periodic direction (for 2D systems only) - boltz\_relax\_time P Relaxation time in fs - boltz\_mu\_min P Minimum value of the chemical potential $\mu$ in eV - boltz\_mu\_max P Maximum value of the chemical potential $\mu$ in eV - boltz\_mu\_step R Step for $\mu$ in eV - boltz\_temp\_min P Minimum value of the temperature $T$ in Kelvin - boltz\_temp\_max P Maximum value of the temperature $T$ in Kelvin - boltz\_temp\_step R Step for $T$ in Kelvin - boltz\_tdf\_energy\_step R Energy step for the TDF (eV) - boltz\_tdf\_smr\_fixed\_en\_width P Energy smearing for the TDF (eV) - boltz\_tdf\_smr\_type S Smearing type for the TDF - boltz\_calc\_also\_dos L Calculate also DOS while calculating the TDF - boltz\_dos\_energy\_min P Minimum value of the energy for the DOS in eV - boltz\_dos\_energy\_max P Maximum value of the energy for the DOS in eV - boltz\_dos\_energy\_step R Step for the DOS in eV - smr\_type S Smearing type for the DOS - adpt\_smr L Use adaptive smearing for the DOS - adpt\_smr\_fac R Adaptive smearing prefactor - adpt\_smr\_max P Maximum allowed value for the adaptive energy smearing (eV) - fixed\_en\_width P Energy smearing (if non-adaptive) for the DOS (eV) - boltz\_bandshift L Rigid bandshift of the conduction bands - boltz\_bandshift\_firstband I Index of the first band to shift - boltz\_bandshift\_energyshift P Energy shift of the conduction bands (eV) - ----------------------------------- ------ -------------------------------------------------------------------------- - - : `seedname.win` file keywords controlling the  module (calculation of + +### `BoltzWann` Parameters +| Keyword | Type | Description | +| :--------------------------------------------: | :--: | :------------------------------------------------------------------------- | +| boltzwann | L | Calculate Boltzmann transport coefficients | +| \[boltz\_\]kmesh | I | Dimensions of the uniform interpolation \(k\)-mesh (one or three integers) | +| \[boltz\_\]kmesh\_spacing | R | Minimum spacing between \(k\) points in Å\(^{-1}\) | +| boltz\_2d\_dir | S | Non-periodic direction (for 2D systems only) | +| boltz\_relax\_time | P | Relaxation time in fs | +| boltz\_mu\_min | P | Minimum value of the chemical potential \(\mu\) in eV | +| boltz\_mu\_max | P | Maximum value of the chemical potential \(\mu\) in eV | +| boltz\_mu\_step | R | Step for \(\mu\) in eV | +| boltz\_temp\_min | P | Minimum value of the temperature \(T\) in Kelvin | +| boltz\_temp\_max | P | Maximum value of the temperature \(T\) in Kelvin | +| boltz\_temp\_step | R | Step for \(T\) in Kelvin | +| boltz\_tdf\_energy\_step | R | Energy step for the TDF (eV) | +| boltz\_tdf\_smr\_fixed\_en\_width | P | Energy smearing for the TDF (eV) | +| boltz\_tdf\_smr\_type | S | Smearing type for the TDF | +| boltz\_calc\_also\_dos | L | Calculate also DOS while calculating the TDF | +| boltz\_dos\_energy\_min | P | Minimum value of the energy for the DOS in eV | +| boltz\_dos\_energy\_max | P | Maximum value of the energy for the DOS in eV | +| boltz\_dos\_energy\_step | R | Step for the DOS in eV | +| \[boltz\_\]smr\_type | S | Smearing type for the DOS | +| \[boltz\_\]adpt\_smr | L | Use adaptive smearing for the DOS | +| \[boltz\_\]adpt\_smr\_fac | R | Adaptive smearing prefactor | +| \[boltz\_\]adpt\_smr\_max | P | Maximum allowed value for the adaptive energy smearing (eV) | +| \[boltz\_\]fixed\_en\_width | P | Energy smearing (if non-adaptive) for the DOS (eV) | +| boltz\_bandshift | L | Rigid bandshift of the conduction bands | +| boltz\_bandshift\_firstband | I | Index of the first band to shift | +| boltz\_bandshift\_energyshift | P | Energy shift of the conduction bands (eV) | + +`seedname.win` file keywords controlling the `BoltzWann` 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. -::: - -::: {#parameter_keywords_geninterp} - ------------------------- ------ --------------------------------------------- - Keyword Type Description - - - geninterp L Calculate bands for given set of $k$ points - geninterp\_alsofirstder L Calculate also first derivatives - geninterp\_single\_file L Write a single file or one for each process - ------------------------- ------ --------------------------------------------- - - : `seedname.win` file keywords controlling the Generic Band - Interpolation (`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. -::: + +### `geninterp` Parameters + +| Keyword | Type | Description | +| :----------------------------------: | :--: | :-------------------------------------------- | +| geninterp | L | Calculate bands for given set of \(k\) points | +| geninterp\_alsofirstder | L | Calculate also first derivatives | +| geninterp\_single\_file | L | Write a single file or one for each process | + +`seedname.win` file keywords controlling the Generic Band Interpolation (`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. Global variables {#sec:postw90-globalflags} ---------------- From 8ebeb8942f15d415313f06acdfd4d9eee7a1c8b3 Mon Sep 17 00:00:00 2001 From: yuhao Date: Wed, 14 Feb 2024 18:32:48 +0100 Subject: [PATCH 3/5] Update some links --- docs/docs/user_guide/introduction.md | 2 +- docs/docs/user_guide/wannier90/files.md | 5 ++--- docs/docs/user_guide/wannier90/projections.md | 4 ++-- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/docs/user_guide/introduction.md b/docs/docs/user_guide/introduction.md index 18944467..be4f08d6 100644 --- a/docs/docs/user_guide/introduction.md +++ b/docs/docs/user_guide/introduction.md @@ -18,7 +18,7 @@ about the `wannier90` code, check the official repository of about its functionalities. Finally, many frequently asked questions are answered in -Appendix [2](#chap:faq){reference-type="ref" reference="chap:faq"}. An +Appendix [FAQs](../appendices/faq/). An expanded FAQ session may be found on the Wiki page of the GitHub repository at . diff --git a/docs/docs/user_guide/wannier90/files.md b/docs/docs/user_guide/wannier90/files.md index 34792669..c77a6b1d 100644 --- a/docs/docs/user_guide/wannier90/files.md +++ b/docs/docs/user_guide/wannier90/files.md @@ -5,7 +5,7 @@ INPUT. The master input file; contains the specification of the system and any parameters for the run. For a description of input parameters, see Chapter [Parameters](../parameters); for examples, see -Section [`seedname.win`](#seedname.win) and +Section [`seedname.win`](../sample_inputs/#master-input-file-seednamewin) and the `wannier90` Tutorial. ### Units @@ -351,8 +351,7 @@ gradient of $\Omega$ with respect to variations in the unitary matrices $\mathbf{U}^{(\mathbf{k})}$, and the last is the time taken (in seconds). Depending on the input parameters used, the procedure either runs for `num_iter` iterations, or a convergence criterion is applied on -$\Omega$. See Section [2.8](#sec:wann_params){reference-type="ref" -reference="sec:wann_params"} for details. +$\Omega$. See Section [Wannierise Parameters](../parameters/#wannierise-parameters) for details. Similarly, the command diff --git a/docs/docs/user_guide/wannier90/projections.md b/docs/docs/user_guide/wannier90/projections.md index 066659eb..477f9e01 100644 --- a/docs/docs/user_guide/wannier90/projections.md +++ b/docs/docs/user_guide/wannier90/projections.md @@ -31,8 +31,8 @@ equation but rather the *real* (in the sense of non-imaginary) states $\Theta_{lm_{\mathrm{r}}}$, obtained by a unitary transformation. For example, the canonical eigenstates associated with $l=1$, $m=\{-1,0,1\}$ are not the real p$_{x}$, p$_{y}$ and p$_{z}$ that we want. See -Section [3.4](#sec:orbital-defs){reference-type="ref" -reference="sec:orbital-defs"} for our mathematical conventions regarding +Section [Orbital Definitions](../projections/#orbital-definitions) +for our mathematical conventions regarding projection orbitals for different $n$, $l$ and $m_{\mathrm{r}}$. We use the following format to specify projections in `.win`: From 74de35397ed0cdadc8a5b42dffb71ee8bcbf09a3 Mon Sep 17 00:00:00 2001 From: yuhao Date: Wed, 14 Feb 2024 20:57:34 +0100 Subject: [PATCH 4/5] Check the format of markdown files. Fix the ref labels and links. Unified the notes format. Minor format fixes. --- docs/docs/user_guide/postw90/boltzwann.md | 2 +- docs/docs/user_guide/postw90/geninterp.md | 1 - docs/docs/user_guide/postw90/gyrotropic.md | 3 +- docs/docs/user_guide/postw90/postw90params.md | 67 ++++++++++--------- docs/docs/user_guide/wannier90/files.md | 4 +- docs/docs/user_guide/wannier90/parameters.md | 41 +++++++----- docs/docs/user_guide/wannier90/postproc.md | 2 +- docs/docs/user_guide/wannier90/transport.md | 6 +- 8 files changed, 67 insertions(+), 59 deletions(-) diff --git a/docs/docs/user_guide/postw90/boltzwann.md b/docs/docs/user_guide/postw90/boltzwann.md index 7065b3b1..f60c992c 100644 --- a/docs/docs/user_guide/postw90/boltzwann.md +++ b/docs/docs/user_guide/postw90/boltzwann.md @@ -14,7 +14,7 @@ Table [ `BoltzWann` Parameters](../postw90params/#boltzwann-parameters). An example of a Boltzmann transport calculation can be found in the `wannier90` Tutorial. -!!!Note +!!! note By default, the code assumes to be working with a 3D bulk material, with periodicity along all three spatial directions. If you are interested in studying 2D systems, set the correct value for the diff --git a/docs/docs/user_guide/postw90/geninterp.md b/docs/docs/user_guide/postw90/geninterp.md index 84042324..b200091f 100644 --- a/docs/docs/user_guide/postw90/geninterp.md +++ b/docs/docs/user_guide/postw90/geninterp.md @@ -7,7 +7,6 @@ points provided by the user. The list of parameters of the Generic Band Interpolation module are summarized in - Table [ `geninterp` Parameters](../postw90params/#geninterp-parameters). The list of input $k$ points for which the band have to be calculated is read from the file named diff --git a/docs/docs/user_guide/postw90/gyrotropic.md b/docs/docs/user_guide/postw90/gyrotropic.md index 6fbdd4ac..ad4c214e 100644 --- a/docs/docs/user_guide/postw90/gyrotropic.md +++ b/docs/docs/user_guide/postw90/gyrotropic.md @@ -142,7 +142,8 @@ $$ The summations over $n$ and $l$ span the occupied ($o$) and empty ($e$) bands respectively, $\omega_{ln}=(E_l-E_n)/\hbar$, and ${\bm A}_{ln}({\bm k})$ is given by -[Berry Eq. (3)](../berry/#mjx-eqn:eq:berry-connection-matrix) +[Berry Eq. (3)](../berry/#mjx-eqn:eq:berry-connection-matrix). + Finally, the matrix $B_{nl}^{ac}$ has both orbital and spin contributions given by diff --git a/docs/docs/user_guide/postw90/postw90params.md b/docs/docs/user_guide/postw90/postw90params.md index 4d783941..3cd23a8b 100644 --- a/docs/docs/user_guide/postw90/postw90params.md +++ b/docs/docs/user_guide/postw90/postw90params.md @@ -93,7 +93,7 @@ The currently available modules in `postw90.x` are: spin Hall conductivity, including anomalous Hall conductivity, orbital magnetisation, optical conductivity, nonlinear shift current and spin Hall conductivity (see - Chap. [berry](../berry) and examples 18, 19, 25, 29 and 30 of the + Chap. [Berry](../berry) and examples 18, 19, 25, 29 and 30 of the tutorial). It also includes an option to compute $k\cdot p$ expansion coefficients (see Sec. [kdotp](../berry/#sec:kdotp) and example 33 of the tutorial). @@ -101,15 +101,15 @@ The currently available modules in `postw90.x` are: - `gyrotropic`: Calculation of gyrotropic properties, including natural and current0induced optical rotation, and the current-induced magnetization (see - Chap. [gyrotropic](../gyrotropic) and examples of the tutorial). + Chap. [Gyrotropic](../gyrotropic) and examples of the tutorial). - `BoltzWann`: Calculation of electronic transport properties for bulk materials using the semiclassical Boltzmann transport equation (see - Chap. [ch:boltzwann](../boltzwann) and example 16 of the tutorial). + Chap. [BoltzWann](../boltzwann) and example 16 of the tutorial). - `geninterp` (Generic Band Interpolation): Calculation band energies (and band derivatives) on a generic list of $k$ points (see - Chap. [ch:geninterp](../geninterp)). + Chap. [Geninterp](../geninterp)). Keyword List ------------ @@ -409,12 +409,13 @@ The default value is 1 if `spinors=true`, 2 otherwise. Scissors shift applied to the conduction bands. -**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 -`boltz_bandshift` instead. If you are calculating spin Hall -conductivity, consider using `shc_bandshift` instead. +!!! 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 + `boltz_bandshift` instead. If you are calculating spin Hall + conductivity, consider using `shc_bandshift` instead. The units are eV. The default value is 0 eV (i.e., no scissors shift applied). @@ -718,9 +719,9 @@ The valid options for this parameter are: - `seedname-path.kpt` (list of $k$-points along the path, written in the `pwscf` format) -- `curv` Minus the Berry curvature given by +- `curv` Minus the Berry curvature given by [Berry Eq. (15)](../berry/#mjx-eqn:eq:ahc) of - Ch. [berry](../berry), in units of ` berry_curv_unit`. The following + Ch. [Berry](../berry), in units of ` berry_curv_unit`. The following files are created: - `seedname-curv.dat` (data file) @@ -729,9 +730,9 @@ The valid options for this parameter are: - `seedname-curv_{x,y,z}.py` (`python` scripts) -- `morb` The integrand of the $k$-space orbital magnetization formula +- `morb` The integrand of the $k$-space orbital magnetization formula \[[Berry Eq. (16)](../berry/#mjx-eqn:eq:morb) of - Ch. [berry](../berry)\] in eV$\cdot$Å$^2$. Four output files are + Ch. [Berry](../berry)\] in eV$\cdot$Å$^2$. Four output files are created: - `seedname-morb.dat` (data file) @@ -741,9 +742,9 @@ The valid options for this parameter are: - `seedname-morb_{x,y,z}.py` (`python` scripts) - `shc` The band-projected Berry curvature-like term of spin Hall - conductivity given by + conductivity given by [Berry Eq. (19)](../berry/#mjx-eqn:eq:kubo_shc_berry) of - Ch. [berry](../berry), in units of ` berry_curv_unit`. The following + Ch. [Berry](../berry), in units of ` berry_curv_unit`. The following files are created: - `seedname-shc.dat` (data file) @@ -755,11 +756,11 @@ The valid options for this parameter are: - Any combination of the above. The following combinations are of special interest - `kpath_task = bands+curv` + - `kpath_task = bands+curv` - `kpath_task = bands+morb` + - `kpath_task = bands+morb` - `kpath_task = bands+shc` + - `kpath_task = bands+shc` They generate the following files: @@ -884,11 +885,12 @@ The valid options for this parameter are: The default value is `fermi_lines`. -Note: When `kslice_fermi_lines_colour = none` the `gnuplot` scripts draw -the $k$-slices with a square shape, even when ` kslice_b1` and -`kslice_b2` below are not at right angles, or do not have equal lengths. -(The `python` scripts draw the slices with the correct parallelogram -shape.) +!!! note + When `kslice_fermi_lines_colour = none` the `gnuplot` scripts draw + the $k$-slices with a square shape, even when ` kslice_b1` and + `kslice_b2` below are not at right angles, or do not have equal lengths. + (The `python` scripts draw the slices with the correct parallelogram + shape.) ### `real(kind=dp) :: kslice_corner(3)` @@ -1180,14 +1182,15 @@ values, the $\sigma_{xy}^{\text{spin}z}$ is computed. Shift all conduction bands by a given amount (defined by `shc_bandshift_energyshift`). -Note: this flag slightly differs from the global `scissors_shift` flag: -with `shc_bandshift`, an exact rigid shift is applied *after* -interpolation; `scissors_shift` applies instead the shift *before* -interpolation. As a consequence, results may slightly differ (and this -is why we provide both possibilities). Note also that with -`scissors_shift` you have to provide the number of valence bands -`num_valence_bands`, while with `shc_bandshift` you should provide the -first band to shift `shc_bandshift_firstband` = `num_valence_bands`$+1$. +!!! note + this flag slightly differs from the global `scissors_shift` flag: + with `shc_bandshift`, an exact rigid shift is applied *after* + interpolation; `scissors_shift` applies instead the shift *before* + interpolation. As a consequence, results may slightly differ (and this + is why we provide both possibilities). Note also that with + `scissors_shift` you have to provide the number of valence bands + `num_valence_bands`, while with `shc_bandshift` you should provide the + first band to shift `shc_bandshift_firstband` = `num_valence_bands`$+1$. The default value is `false`. diff --git a/docs/docs/user_guide/wannier90/files.md b/docs/docs/user_guide/wannier90/files.md index c77a6b1d..d7789c8e 100644 --- a/docs/docs/user_guide/wannier90/files.md +++ b/docs/docs/user_guide/wannier90/files.md @@ -195,7 +195,7 @@ plotting. This part of the output files provides information on the $\mathrm{b}$-vectors and weights chosen to satisfy the condition of -Eq. [B1](../parameters/mjx-eqn:eq:B1). +Eq. [B1](../parameters/#mjx-eqn:eq:B1). *---------------------------------- K-MESH ----------------------------------* +----------------------------------------------------------------------------+ @@ -982,7 +982,7 @@ right lead which is in contact with the conductor region. Note that 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 -## `seedname.unkg` {#sec:files_unkg} +## `seedname.unkg` INPUT. Read if `transport_mode = lcr` and `tran_read_ht = .FALSE.`. The first line is the number of diff --git a/docs/docs/user_guide/wannier90/parameters.md b/docs/docs/user_guide/wannier90/parameters.md index 56f8e65f..c0ec1c10 100644 --- a/docs/docs/user_guide/wannier90/parameters.md +++ b/docs/docs/user_guide/wannier90/parameters.md @@ -197,7 +197,7 @@ window. | dist_cutoff | P | Cut-off for the distance between WF | | dist_cutoff_mode | S | Dimension in which the distance between WF is calculated | | translation_centre_frac | R | Centre of the unit cell to which final WF are translated | -| use_ws_distance | L | Improve interpolation using minimum distance between WFs, see [Chap. 9](../notes_interpolations)| +| use_ws_distance | L | Improve interpolation using minimum distance between WFs, see Chap. [Some notes on the interpolation](../notes_interpolations)| | ws_distance_tol | R | Absolute tolerance for the distance to equivalent positions. | | ws_search_size | I | Maximum extension in each direction of the super-cell of the Born-von Karmann cell to search for points inside the Wigner-Seitz cell | | write_u_matrices | L | Write $U^{(\bm{k})}$ and $U^{dis(\bm{k})}$ matrices to files | @@ -369,9 +369,10 @@ end kpoints There is no default. -**Note**: There is an utility provided with `wannier90`, called -`kmesh.pl`, which helps to generate the explicit list of $k$ points -required by `wannier90`. See Sec. [`kmesh.pl`](../../appendices/utilities#kmeshpl). +!!! note + There is an utility provided with `wannier90`, called + `kmesh.pl`, which helps to generate the explicit list of $k$ points + required by `wannier90`. See Sec. [`kmesh.pl`](../../appendices/utilities#kmeshpl). ### `logical :: gamma_only` @@ -572,9 +573,10 @@ $A_{mn}^{(\mathbf{k})}$. For additional information on the behavior and on the added block, see Sec. [`auto_projections` block](../postproc#auto_projections-block). -**Note:** the interface code (e.g. `pw2wannier90.x`) must have at least -one implementation of a method to automatically generate initial -projections in order for this option to be usable. +!!! note + the interface code (e.g. `pw2wannier90.x`) must have at least + one implementation of a method to automatically generate initial + projections in order for this option to be usable. The default value of this parameter is `false`. @@ -693,10 +695,11 @@ To activate projectability disentanglement procedure, which selectively discard/disentangle/freeze state $\vert n \mathbf{k}\rangle$ based on its projectability onto some localized atomic orbitals. -Note: this requires the `amn` file is properly normalized, i.e., -projectability computed from $A A^\dagger$ must be smaller than or equal -to 1. The pseudo-atomic projection satisfies such requirement, see -[Projections via pseudo-atomic orbitals in pw2wannier90](../projections#projections-via-pseudo-atomic-orbitals-in-pw2wannier90). +!!! note + this requires the `amn` file is properly normalized, i.e., + projectability computed from $A A^\dagger$ must be smaller than or equal + to 1. The pseudo-atomic projection satisfies such requirement, see + [Projections via pseudo-atomic orbitals in pw2wannier90](../projections#projections-via-pseudo-atomic-orbitals-in-pw2wannier90). Additionally, one can combine projectability disentanglement with energy disentanglement, i.e., enable both `dis_proj_min/max` and @@ -1197,11 +1200,12 @@ quatity plotted is - `down`. $|\psi|\times sign(Re\{\psi\})$ if `wannier_plot_spinor_phase = true`, otherwise $|\psi|$ -Note: making a visual representation of a spinor WF is not as -straightforward as for a scalar WF. While a scalar WF is typically a -real valued function, a spinor WF is a complex, two component spinor. -`wannier90` is able to plot several different quantities derived from a -spinor WF which should give you a good idea of the nature of the WF. +!!! note + making a visual representation of a spinor WF is not as + straightforward as for a scalar WF. While a scalar WF is typically a + real valued function, a spinor WF is a complex, two component spinor. + `wannier90` is able to plot several different quantities derived from a + spinor WF which should give you a good idea of the nature of the WF. ### `logical :: wannier_plot_spinor_phase` @@ -1258,8 +1262,9 @@ options for this parameter are: - `xmgrace` -Note: it is possible to request output in both formats eg -`bands_format = gnuplot xmgrace` +!!! note + it is possible to request output in both formats eg + `bands_format = gnuplot xmgrace` ### `integer :: bands_plot_project(:)` diff --git a/docs/docs/user_guide/wannier90/postproc.md b/docs/docs/user_guide/wannier90/postproc.md index c672447d..938dd68c 100644 --- a/docs/docs/user_guide/wannier90/postproc.md +++ b/docs/docs/user_guide/wannier90/postproc.md @@ -101,7 +101,7 @@ crystallographic co-ordinates relative to the direct lattice vectors. `l mr r`: three integers; $l$ and $m_\mathrm{r}$ specify the angular part $\Theta_{lm_{\mathrm{r}}}(\theta,\varphi)$, and $\mathrm{r}$ specifies the radial part $R_{\mathrm{r}}(r)$ of the projection function -(see Tables [Angular functions](../projections/#angular-functions), [Hybrids](../projections#hybrids) and [Radial functions](../projections/#radial-functions). +(see Tables [Angular functions](../projections/#angular-functions), [Hybrids](../projections#hybrids) and [Radial functions](../projections/#radial-functions)). `z-axis`: three real numbers; default is `0.0 0.0 1.0`; defines the axis from which the polar angle $\theta$ in spherical polar coordinates is diff --git a/docs/docs/user_guide/wannier90/transport.md b/docs/docs/user_guide/wannier90/transport.md index d28298b7..beaf3da6 100644 --- a/docs/docs/user_guide/wannier90/transport.md +++ b/docs/docs/user_guide/wannier90/transport.md @@ -17,7 +17,7 @@ calculated using the Hamiltonian in the Wannier function basis of the system found by `wannier90`. Setting `tran_read_ht = TRUE` allows the user to provide an external Hamiltonian matrix file `seedname_htB.dat`, from which the properties are found. See -Section [sec:post-p parameters](../parameters) +Section [Post-Processing](../parameters#post-processing) for more details of the keywords required for such calculations. ### `transport_mode = lcr` @@ -46,7 +46,7 @@ transport properties of an lcr system from a single external files provide in the `tran_read_ht = TRUE` case are instead built from the Wannier function basis directly. As such, strict rules apply to the system geometry, which is shown in -Figure [7.1](#fig:2c2). These +Figure [below](#fig:lcr-2c2). These rules are as follows: - Left and right leads must be identical and periodic. @@ -121,7 +121,7 @@ $\tilde{u}_{m\mathbf{k}}(\mathbf{G})$ are required. These are found in an additional file (`seedname.unkg`) that should be provided by the interface between the DFT code and `wannier90` . A detailed description of this file may be found in -Section [`seedname.unkg`](../files/#seedname.unkg). +Section [`seedname.unkg`](../files/#seednameunkg). Additionally, the following keywords are also required in the input file: From b8883a49c11c5fbc8428b7693d18b219cc000d9f Mon Sep 17 00:00:00 2001 From: yuhao Date: Thu, 15 Feb 2024 10:25:06 +0100 Subject: [PATCH 5/5] Remove absolute number in cross-file equation ref --- docs/docs/user_guide/postw90/gyrotropic.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/docs/user_guide/postw90/gyrotropic.md b/docs/docs/user_guide/postw90/gyrotropic.md index ad4c214e..06812d91 100644 --- a/docs/docs/user_guide/postw90/gyrotropic.md +++ b/docs/docs/user_guide/postw90/gyrotropic.md @@ -142,8 +142,7 @@ $$ The summations over $n$ and $l$ span the occupied ($o$) and empty ($e$) bands respectively, $\omega_{ln}=(E_l-E_n)/\hbar$, and ${\bm A}_{ln}({\bm k})$ is given by -[Berry Eq. (3)](../berry/#mjx-eqn:eq:berry-connection-matrix). - +[Berry Eq. \[Berry connection matrix\]](../berry/#mjx-eqn:eq:berry-connection-matrix). Finally, the matrix $B_{nl}^{ac}$ has both orbital and spin contributions given by