Pass markdownlint on user guide wannier90

.markdownlint.yaml

@@ -17,3 +17,4 @@ MD033:
     - sub
     - a
     - sup
+    - code

.pre-commit-config.yaml

@@ -35,4 +35,4 @@ repos:
   rev: v0.12.1
   hooks:
   - id: markdownlint-cli2
-    args: ['--fix']
+    args: ['--fix', 'docs/**.md']

docs/docs/user_guide/appendices/utilities.md

@@ -1,10 +1,9 @@
-
-## Utilities
+# Utilities
 
 The `wannier90` code is shipped with a few utility programs that may be
 useful in some occasions. In this chapter, we describe their use.
 
-### `kmesh.pl`
+## `kmesh.pl`
 
 The `wannier90` code requires the definition of a full Monkhorst--Pack
 grid of $k$ points. In the input file the size of this mesh is given by
@@ -55,7 +54,7 @@ allows to provide the $k$ point coordinates with the accuracy required
 by `wannier90`, and moreover it makes sure that the $k$ grid used in the
 ab-initio code and in `wannier90` are the same.
 
-### `w90chk2chk.x`
+## `w90chk2chk.x`
 
 During the calculation of the Wannier functions, `wannier90` produces a
 `.chk` file that contains some information to restart the calculation.
@@ -125,7 +124,7 @@ A typical use is the following:
 
 5. Run the `postw90` code.
 
-### `PL_assessment`
+## `PL_assessment`
 
 The function of this utility is to assess the length of a principal
 layer (in the context of a Landauer-Buttiker quantum conductance
@@ -171,7 +170,7 @@ four columns
 
 4. Maximum absolute value in (2)
 
-### `w90vdw`
+## `w90vdw`
 
 This utility provides an implementation of a method for calculating van
 der Waals energies based on the idea of density decomposition via MLWFs.
@@ -187,15 +186,15 @@ For further details of this program, please see the documentation in
 `utility/w90vdw/doc/` and the related examples in
 `utility/w90vdw/examples/`.
 
-### `w90pov`
+## `w90pov`
 
 An utility to create Pov files (to render the Wannier functions using
 the PovRay utility) is provided inside `utility/w90pov`.
 
 Please refer to the documentation inside `utility/w90pov/doc` for more
 information.
 
-### `k_mapper.py`
+## `k_mapper.py`
 
 The `wannier90` code requires the definition of a full Monkhorst--Pack
 grid of $\mathbf{k}$-vectors, which can be obtained by means of the
@@ -214,7 +213,7 @@ path/k_mapper.py nx ny nz QE_nscf_output
 where `path` is the path of `utility` folder, `QE_nscf_output` is the
 path of the QE nscf output file given to Yambo.
 
-### `gw2wannier90.py`
+## `gw2wannier90.py`
 
 This utility allows to sort in energy the input data of `wannier90`
 (e.g. overlap matrices and energy eigenvalues). `gw2wannier90.py` allows
@@ -231,9 +230,11 @@ where `path` is the path of
 
 Available options are:
 
-    mmn, amn, spn, unk, uhu, uiu,
-    spn_formatted, unk_formatted, uhu_formatted, uiu_formatted,
-    write_formatted
+```bash title="Terminal"
+mmn, amn, spn, unk, uhu, uiu,
+spn_formatted, unk_formatted, uhu_formatted, uiu_formatted,
+write_formatted
+```
 
 If no options are specified, all the files
 (`mmn, amn, spn, UNK, uHu, uIu`) are considered.
@@ -248,7 +249,7 @@ In default, the output format is the same as the input format. To
 generate formatted files with unformatted input, use option:
 `write_formatted`
 
-### `w90spn2spn.x`
+## `w90spn2spn.x`
 
 The interface between ab-initio code and `wannier90` (e.g.
 `pw2wannier90.x`) can produce a `.spn` file that is used by `postw90` to
@@ -326,7 +327,7 @@ rerun `pw2wannier90.x`, then `w90spn2spn.x` can be useful. Also, once a
 if `spn_formatted` is set to `true` in `postw90` input file
 `seedname.win`.
 
-### `write_pdwf_projectors.py`
+## `write_pdwf_projectors.py`
 
 A python script to extract projectors from a `UPF` file and write them
 into a `pw2wannier90.x`-recognizable `dat` file, which can be used to

docs/docs/user_guide/postw90/berry.md

@@ -7,7 +7,7 @@ curvature, orbital magnetization and spin Hall conductivity are also
 called when `kpath = true` and `kpath_task = {curv,morb,shc}`, or when
 `kslice = true` and `kslice_task = {curv,morb,shc}`.
 
-### Background: Berry connection and curvature
+## Background: Berry connection and curvature
 
 The Berry connection is defined in terms of the cell-periodic Bloch
 states $\vert u_{n{\bf k}}\rangle=e^{-i{\bf k}\cdot{\bf r}}\vert
@@ -56,7 +56,7 @@ $$
 \end{equation}
 $$
 
-### `berry_task=kubo`: optical conductivity and joint density of states
+## `berry_task=kubo`: optical conductivity and joint density of states
 
 The Kubo-Greenwood formula for the optical conductivity of a crystal in
 the independent-particle approximation reads
@@ -167,8 +167,8 @@ f_{n{\bf k}}(1-f_{m{\bf k}})
 \end{equation}
 $$
 
-Equations $\eqref{eq:lorentzian}$--$\eqref{eq:jdos}$ contain the parameter $\eta$, whose value can be
-chosen using the keyword
+Equations $\eqref{eq:lorentzian}$--$\eqref{eq:jdos}$ contain the parameter
+$\eta$, whose value can be chosen using the keyword
 `[kubo_]smr_fixed_en_width`. Better results can often be achieved by
 adjusting the value of $\eta$ for each pair of states, i.e.,
 $\eta\rightarrow \eta_{nm\bf k}$. This is done as follows (see
@@ -203,7 +203,7 @@ $$
 whose independent components are written as a function
 of frequency onto nine separate files.
 
-### `berry_task=ahc`: anomalous Hall conductivity
+## `berry_task=ahc`: anomalous Hall conductivity
 
 The antisymmetric tensor $\sigma^{\rm A}_{\alpha\beta}$ is odd under
 time reversal, and therefore vanishes in non-magnetic systems, while in
@@ -260,7 +260,7 @@ Eq. $\eqref{eq:ahc}$ can
 be evaluated by Wannier interpolation as described in
 Refs. [@wang-prb06; @lopez-prb12], with no truncation involved.
 
-### `berry_task=morb`: orbital magnetization
+## `berry_task=morb`: orbital magnetization
 
 The ground-state orbital magnetization of a crystal is given
 by [@xiao-rmp10; @ceresoli-prb06]
@@ -288,7 +288,7 @@ Note that the definition of ${\bf M}^{\rm orb}({\bf k})$ used here
 differs by a factor of $-1/2$ from the one in Eq. (97) and Fig. 2 of
 that work.
 
-### `berry_task=shc`: spin Hall conductivity {#sec:shc}
+## `berry_task=shc`: spin Hall conductivity {#sec:shc}
 
 The Kubo-Greenwood formula for the intrinsic spin Hall conductivity
 (SHC) of a crystal in the independent-particle approximation reads
@@ -328,8 +328,10 @@ elements are evaluated,
 
 $$
 \begin{equation}
-\langle u_{n{\bf k}}\vert\sigma_\gamma H_{\bf k}\vert u_{m{\bf k}+{\bf b}}\rangle,
-\langle u_{n{\bf k}}\vert\sigma_\gamma \vert u_{m{\bf k}+{\bf b}}\rangle, \gamma = x, y, z
+\langle u_{n{\bf k}}\vert\sigma_\gamma H_{\bf k}
+\vert u_{m{\bf k}+{\bf b}}\rangle,
+\langle u_{n{\bf k}}\vert \sigma_\gamma \vert u_{m{\bf k}+{\bf b}}\rangle,
+\gamma = x, y, z
 \end{equation}
 $$
 
@@ -415,7 +417,7 @@ or
 > principles using maximally localized Wannier functions*,
 > Phys. Rev. B. 99, 235113 (2019), DOI:10.1103/PhysRevB.99.235113.
 
-### `berry_task=sc`: shift current
+## `berry_task=sc`: shift current
 
 The shift-current contribution to the second-order response is
 characterized by a frequency-dependent third-rank tensor [@sipe-prb00]
@@ -476,7 +478,7 @@ the keyword `[kubo_]adpt_smr`.
 Please cite Ref. [@ibanez-azpiroz_ab_2018] when publishing shift-current
 results using this method.
 
-### `berry_task=kdotp`: $k\cdot p$ coefficients {#sec:kdotp}
+## `berry_task=kdotp`: $k\cdot p$ coefficients {#sec:kdotp}
 
 Consider a Hamiltonian
 
@@ -549,8 +551,10 @@ where $a,b=x,y,z$, and
 $$
 \begin{equation}
 \begin{aligned}
-&H_{a}^{(W)}(0)=\left. \dfrac{\partial H^{(W)}(\bm{k})}{\partial k_{a}}\right\rvert_{\bm{k}=0}\\
-&H_{ab}^{(W)}(0)=\left. \dfrac{\partial^{2} H^{(W)}(\bm{k})}{\partial k_{a}\partial k_{b}}\right\rvert_{\bm{k}=0}
+&H_{a}^{(W)}(0)=\left. \dfrac{\partial H^{(W)}(\bm{k})}{\partial k_{a}}
+\right\rvert_{\bm{k}=0}\\
+&H_{ab}^{(W)}(0)=\left. \dfrac{\partial^{2} H^{(W)}(\bm{k})}
+{\partial k_{a}\partial k_{b}}\right\rvert_{\bm{k}=0}
 \end{aligned}
 \end{equation}
 $$
@@ -562,8 +566,10 @@ $H(\bm{k})$,
 $$
 \begin{equation}
 \label{eq:Hbar}
-H(\bm{k})=\overbrace{\overline{H}}^{H^{0}} + \overbrace{\sum_{a}\overline{H}_{a}k_{a}
-+\dfrac{1}{2}\sum_{ab}\overline{H}_{ab}k_{a}k_{b}}^{H^{\prime}} + \mathcal{O}(k^{3}),
+H(\bm{k})=\overbrace{\overline{H}}^{H^{0}} +
+\overbrace{\sum_{a}\overline{H}_{a}k_{a}
++\dfrac{1}{2}\sum_{ab}\overline{H}_{ab}k_{a}k_{b}}^{H^{\prime}} +
+\mathcal{O}(k^{3}),
 \end{equation}
 $$
 
@@ -621,13 +627,14 @@ The implementation in `wannier90` follows the scheme proposed in
 Ref. [@ibanez-azpiroz-ArXiv2019], and outputs $\overline{H}_{mm'}$ in
 `seedname-kdotp_0.dat`, $\left(\overline{H}_{a}\right)_{mm'}$ in
 `seedname-kdotp_1.dat`, and
-$\left[\left(\overline{H}_{ab}\right)_{mm'} + \left({T}_{ab}\right)_{mm'}\right]/2$
+$\left[\left(\overline{H}_{ab}\right)_{mm'} +
+\left({T}_{ab}\right)_{mm'}\right]/2$
 in `seedname-kdotp_2.dat`.
 
 Please cite Ref. [@ibanez-azpiroz-ArXiv2019] when publishing $k\cdot p$
 results using this method.
 
-### Needed matrix elements
+## Needed matrix elements
 
 All the quantities entering the formulas for the optical conductivity
 and AHC can be calculated by Wannier interpolation once the Hamiltonian
@@ -637,7 +644,8 @@ and position matrix elements $\langle {\bf 0}n\vert H\vert
 elements are readily available at the end of a standard MLWF calculation
 with `wannier90`. In particular, $\langle {\bf
   0}n\vert {\bf r}\vert {\bf R}m\rangle$ can be calculated by Fourier
-transforming the overlap matrices in [Methodology Eq. \[overlap matrices\]](../wannier90/methodology.md#mjx-eqn:eq:overlap-matrix),
+transforming the overlap matrices in
+[Methodology Eq. \[overlap matrices\]](../wannier90/methodology.md#mjx-eqn:eq:overlap-matrix),
 
 $$
 \begin{equation}
@@ -691,7 +699,8 @@ further matrix elements are needed:
 $$
 \begin{equation}
 \langle u_{n{\bf k}}\vert
-\sigma_\gamma H_{\bf k}\vert u_{m{\bf k}+{\bf b}}\rangle, \langle u_{n{\bf k}}\vert
+\sigma_\gamma H_{\bf k}\vert u_{m{\bf k}+{\bf b}}\rangle,
+\langle u_{n{\bf k}}\vert
 \sigma_\gamma \vert u_{m{\bf k}+{\bf b}}\rangle,
 \gamma = x, y, z
 \end{equation}

docs/docs/user_guide/postw90/boltzwann.md

@@ -32,7 +32,7 @@ obtained using the `BoltzWann` module:
 > basis*,
 > Comp. Phys. Comm. 185, 422 (2014), DOI:10.1016/j.cpc.2013.09.015.
 
-### Theory {#sec:boltzwann-theory}
+## Theory
 
 The theory of the electronic transport using the Boltzmann transport
 equations can be found for instance in
@@ -45,8 +45,10 @@ flux density) $\mathrm{\bm{J}}_Q$ can be written, respectively, as
 $$
 \begin{equation}
 \begin{aligned}
-  \mathrm{\bm{J}}   &= \mathrm{\bm{\sigma}}(\mathrm{\bm{E}} - \mathrm{\bm{S}} \mathrm{\bm{\nabla }}T) \\
-  \mathrm{\bm{J}}_Q &= T \mathrm{\bm{\sigma }}\mathrm{\bm{S}} \mathrm{\bm{E}} - \mathrm{\bm{K}} \mathrm{\bm{\nabla }}T,
+  \mathrm{\bm{J}}   &= \mathrm{\bm{\sigma}}(\mathrm{\bm{E}} - \mathrm{\bm{S}}
+  \mathrm{\bm{\nabla }}T) \\
+  \mathrm{\bm{J}}_Q &= T \mathrm{\bm{\sigma }}\mathrm{\bm{S}} \mathrm{\bm{E}} -
+  \mathrm{\bm{K}} \mathrm{\bm{\nabla }}T,
 \end{aligned}
 \end{equation}
 $$
@@ -61,7 +63,8 @@ $\mathrm{\bm{K}}$ are $3\times 3$ tensors, in general.
     heat current per unit of temperature gradient in open-circuit
     experiments (i.e., with $\mathrm{\bm{J}}=0$) is not precisely
     $\mathrm{\bm{K}}$, but
-    $\mathrm{\bm{\kappa }}= \mathrm{\bm{K}}-\mathrm{\bm{S}} \mathrm{\bm{\sigma }}\mathrm{\bm{S}} T$
+    $\mathrm{\bm{\kappa }}= \mathrm{\bm{K}}-\mathrm{\bm{S}}
+    \mathrm{\bm{\sigma }}\mathrm{\bm{S}} T$
     (see for instance Eq. (7.89) of Ref. [@ziman-book72] or Eq. (XI-57b) of
     Ref. [@grosso-book00]). The thermal conductivity $\mathrm{\bm{\kappa}}$
     can be then calculated from the $\mathrm{\bm{\sigma}}$,
@@ -74,9 +77,16 @@ $$
 \begin{equation}
 \label{eq:boltz-sigmas}
 \begin{aligned}
-  \mathrm{[\bm{\sigma}]}_{ij}(\mu,T)&=e^2 \int_{-\infty}^{+\infty} d\varepsilon \left(-\frac {\partial f(\varepsilon,\mu,T)}{\partial \varepsilon}\right)\Sigma_{ij}(\varepsilon), \\
-  [\mathrm{\bm{\sigma }}\mathrm{\bm{S}}]_{ij}(\mu,T)&=\frac e T \int_{-\infty}^{+\infty} d\varepsilon \left(-\frac {\partial f(\varepsilon,\mu,T)}{\partial \varepsilon}\right)(\varepsilon-\mu)\Sigma_{ij}(\varepsilon),\\
-  [\mathrm{\bm{K}}]_{ij}(\mu,T)&=\frac 1 T \int_{-\infty}^{+\infty} d\varepsilon \left(-\frac {\partial f(\varepsilon,\mu,T)}{\partial \varepsilon}\right)(\varepsilon-\mu)^2 \Sigma_{ij}(\varepsilon),
+  \mathrm{[\bm{\sigma}]}_{ij}(\mu,T)&=e^2 \int_{-\infty}^{+\infty} d\varepsilon
+  \left(-\frac {\partial f(\varepsilon,\mu,T)}{\partial \varepsilon}\right)
+  \Sigma_{ij}(\varepsilon), \\
+  [\mathrm{\bm{\sigma }}\mathrm{\bm{S}}]_{ij}(\mu,T)&=\frac e T
+  \int_{-\infty}^{+\infty} d\varepsilon \left(-\frac {\partial
+  f(\varepsilon,\mu,T)}{\partial \varepsilon}\right)(\varepsilon-\mu)
+  \Sigma_{ij}(\varepsilon),\\
+  [\mathrm{\bm{K}}]_{ij}(\mu,T)&=\frac 1 T \int_{-\infty}^{+\infty}
+  d\varepsilon \left(-\frac {\partial f(\varepsilon,\mu,T)}
+  {\partial \varepsilon}\right)(\varepsilon-\mu)^2 \Sigma_{ij}(\varepsilon),
 \end{aligned}
 \end{equation}
 $$
@@ -98,7 +108,9 @@ tensor, defined as
 
 $$
 \begin{equation}
-\Sigma_{ij}(\varepsilon) = \frac 1 V \sum_{n,\mathrm{\bm{k}}} v_i(n,\mathrm{\bm{k}}) v_j(n,\mathrm{\bm{k}}) \tau(n,\mathrm{\bm{k}}) \delta(\varepsilon - E_{n,k}).
+\Sigma_{ij}(\varepsilon) = \frac 1 V \sum_{n,\mathrm{\bm{k}}}
+v_i(n,\mathrm{\bm{k}}) v_j(n,\mathrm{\bm{k}}) \tau(n,\mathrm{\bm{k}})
+\delta(\varepsilon - E_{n,k}).
 \end{equation}
 $$
 
@@ -115,9 +127,9 @@ approximation* adopted here, $\tau$ is assumed as a constant, i.e., it
 is independent of $n$ and $\mathrm{\bm{k}}$ and its value (in fs) is
 read from the input variable `boltz_relax_time`.
 
-### Files
+## Files
 
-#### `seedname_boltzdos.dat`
+### `seedname_boltzdos.dat`
 
 OUTPUT. Written by `postw90` if `boltz_calc_also_dos` is `true`. Note
 that even if there are other general routines in `postw90` which
@@ -132,7 +144,8 @@ describe the content of the file. Then, there is a line for each energy
 $\varepsilon$ on the grid, containing a number of columns. The first
 column is the energy $\varepsilon$. The following is the DOS at the
 given energy $\varepsilon$. The DOS can either be calculated using the
-adaptive smearing scheme (see the following note) if `boltz_dos_adpt_smr` is `true`, or using
+adaptive smearing scheme (see the following note) if `boltz_dos_adpt_smr`
+is `true`, or using
 a "standard" fixed smearing, whose type and value are defined by
 `boltz_dos_smr_type` and `boltz_dos_smr_fixed_en_width`, respectively.
 If spin decomposition is required (input flag `spin_decomp`), further
@@ -148,7 +161,7 @@ spin-down projection.
     the DOS may be slightly different with respect to that given by the
     `dos` module.
 
-#### `seedname_tdf.dat`
+### `seedname_tdf.dat`
 
 OUTPUT. This file contains the Transport Distribution Function (TDF)
 tensor $\mathrm{\bm{\Sigma}}$ on a grid of energies.
@@ -168,7 +181,7 @@ The energy $\varepsilon$ is in eV, while $\mathrm{\bm{\Sigma}}$ is in
 $\displaystyle\frac{1}{\hbar^2}\cdot{\mathrm{eV}\cdot\mathrm{fs}}\cdot
 {\mathring{\mathrm{A}}^{-1}}$.
 
-#### `seedname_elcond.dat`
+### `seedname_elcond.dat`
 
 OUTPUT. This file contains the electrical conductivity tensor
 $\mathrm{\bm{\sigma}}$ on the grid of $T$ and $\mu$ points.
@@ -183,7 +196,7 @@ The chemical potential is in eV, the temperature is in K, and the
 components of the electrical conductivity tensor ar in SI units, i.e. in
 1/$\Omega$/m.
 
-#### `seedname_sigmas.dat`
+### `seedname_sigmas.dat`
 
 OUTPUT. This file contains the tensor
 $\mathrm{\bm{\sigma}}\mathrm{\bm{S}}$, i.e. the product of the
@@ -200,7 +213,7 @@ symmetric).
 The chemical potential is in eV, the temperature is in K, and the
 components of the tensor ar in SI units, i.e. in A/m/K.
 
-#### `seedname_seebeck.dat`
+### `seedname_seebeck.dat`
 
 OUTPUT. This file contains the Seebeck tensor $\mathrm{\bm{S}}$ on the
 grid of $T$ and $\mu$ points.
@@ -222,10 +235,10 @@ from the other three files (elcond, sigmas and kappa)!
 The chemical potential is in eV, the temperature is in K, and the
 components of the Seebeck tensor ar in SI units, i.e. in V/K.
 
-#### `seedname_kappa.dat`
+### `seedname_kappa.dat`
 
 OUTPUT. This file contains the tensor $\mathrm{\bm{K}}$ defined in
-Sec. [Theory](#sec:boltzwann-theory) on the grid of $T$ and $\mu$ points.
+Sec. [Theory](#theory) on the grid of $T$ and $\mu$ points.
 
 The first lines are comments (starting with \# characters) which
 describe the content of the file. Then, there is a line for each