Update recip_precond docs

recip_precond.rst

@@ -12,18 +12,18 @@ preconditioning.
 is defined as:
 
 .. math::
-   K_{\mathbf{G}, \mathbf{G}^{\prime}}=\delta_{\mathbf{G}, \mathbf{G}^{\prime}} \frac{27+18 x+12 x^2+8 x^3}{27+18 x+12 x^2+8 x^3+16 x^4}
+   P_{\mathbf{G}, \mathbf{G}^{\prime}}=\delta_{\mathbf{G}, \mathbf{G}^{\prime}} \frac{27+18 x+12 x^2+8 x^3}{27+18 x+12 x^2+8 x^3+16 x^4}
 
 where
 
 .. math::
-   x=\frac{\left(\hbar^2|\mathbf{k}+\mathbf{G}|^2\right) / 2 m}{T_i^m}
+   x=\frac{\left(\hbar^2|\mathbf{k}+\mathbf{G}|^2\right) / 2 m}{T_i}
 
-and :math:`T_i^m=<\psi_i^m\left|\left(-\hbar^2 / 2 m\right) \nabla^2\right| \psi_i^m >` 
-which is related to the band :math:`i` that :math:`K` is applied to.
+and :math:`T_i=\left < \psi_i\left|\frac{-\hbar^2}{2 m} \nabla^2\right| \psi_i \right>`
+which is related to the band :math:`i` that :math:`P` is applied to.
 
-In ONETEP, since we do not have the kinetic energy eigenvalues, :math:`x` is
-modified to be:
+In ONETEP, by default we want to avoid calculating the kinetic energy
+eigenvalues, :math:`x` is modified to be:
 
 .. math::
    x=\frac{\frac{1}{2}|\mathbf{G}|^2}{\frac{1}{2}k_0^2}
@@ -34,33 +34,45 @@ Automatic selection of :math:`k_0`
 ==================================
 
 Since ONETEP version 8, it is possible to perform calculations where :math:`k_0`
-is calculated automatically based on the average kinetic energy at each NGWF
-step. I.e.,
+is calculated automatically based on the kinetic energy at each NGWF
+optimisation step. I.e.,
 
 .. math::
-   k_0 = \sqrt{\frac{\mathrm{Max[Tr(KT)]}}{n_\mathrm{occupied\ bands}}}
+   k_0 = \sqrt{\mathrm{Max[Eig[KT]]}}
 
-where :math:`\mathrm{Max[Tr(KT)]}` is the max value of the trace of the kinetic
-energy operator matrix in the NGWF basis, and :math:`n_\mathrm{occupied\ bands}`
-is the number of occupied bands.
+where :math:`K` is the density kernel and :math:`\mathrm{Max[Eig(KT)]}` gives
+the max eigenvalue of the (occupation weighted) kinetic energy matrix in the
+NGWF basis.
 
-It is also possible to perfrom NGWF-specific preconditioning so that no
-band averaging is needed. In this case, each NGWF will have its own :math:`k_0`
-value based on its own kinetic energy expectation value.
-There are a few choices in terms of the kinetic energy to use for the
-preconditioning for each NGWF.
+Note that in the case of multi-kpoint/spin-polarised calculation, k-point/spin
+average is performed and a single :math:`k_0` is obtained for the whole system.
 
-   1. The diagonal elements of :math:`KT`.
-   2. The diagonal elements of :math:`S^{-1}T`.
-   3. The diagonal elements of :math:`T`.
+It is also possible to perfrom NGWF-specific preconditioning. In this case, each
+NGWF will have its own :math:`k_0`. For example, if we use the kinetic energy
+matrix weighted by the occupation numbers :math:`KT`, then for the :math:`i`-th
+NGWF, we have
+
+.. math::
+   k_0^{i} = \sqrt{(KT)_{i}^i}
+
+There are three options for the matrix to use for NGWF-specific preconditioning:
+
+   1. The diagonal elements of :math:`KT`: Occupation weighted kinetic energy.
+   2. The diagonal elements of :math:`S^{-1}T`: Tensor corrected kinetic energy.
+   3. The diagonal elements of :math:`T`: Bare kinetic energy.
+
+Testing is needed to determine which option is the best for specific systems.
+Note that kinetic energy preconditioning can affect the total energy so one
+should always check and make sure the convergence of total energy difference
+(e.g. bettwen a pristine system and a distorted system) is correct.
 
 Keywords
 ========
 
--  ``precond_recip`` [Basic, bool, default ``F``\ ] Turn on reciprocal space
+-  ``precond_recip`` [Basic, bool, default ``T``\ ] Turn on reciprocal space
    kinetic energy preconditioning? [Incompatible with ``precond_real``]
 
--  ``precond_real`` [Basic, bool, default ``T``\ ] Turn on real space
+-  ``precond_real`` [Basic, bool, default ``F``\ ] Turn on real space
    kinetic energy preconditioning? [Incompatible with ``precond_recip`` and 
    automatic :math:`k_0` mode.]