diff --git a/conf.py b/conf.py index 1f3338f..334b956 100644 --- a/conf.py +++ b/conf.py @@ -58,9 +58,9 @@ # built documents. # # The short X.Y version. -version = '7.3' +version = '8.0.0' # The full version, including alpha/beta/rc tags. -release = '7.1.8' +release = '8.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/index_ground_state.rst b/index_ground_state.rst index 58bf426..48478f1 100644 --- a/index_ground_state.rst +++ b/index_ground_state.rst @@ -26,4 +26,5 @@ Ground State Calculation Setup dipole_correction.rst scissor_operator.rst EMFT_in_ONETEP.rst + recip_precond.rst diff --git a/recip_precond.rst b/recip_precond.rst new file mode 100644 index 0000000..00fd54b --- /dev/null +++ b/recip_precond.rst @@ -0,0 +1,82 @@ +======================================== +Kinetic energy preconditioning in ONETEP +======================================== + +:Author: Chengcheng Xiao +:Date: Dec 2025 + +ONETEP at the moment, by default uses a modified Teter reciprocal +preconditioning. + +`The original Teter reciprocal preconditioning function `__ +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} + +where + +.. math:: + x=\frac{\left(\hbar^2|\mathbf{k}+\mathbf{G}|^2\right) / 2 m}{T_i^m} + +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. + +In ONETEP, since we do not have 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} + +and :math:`k_0` is a manually specified number. + +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., + +.. math:: + k_0 = \sqrt{\frac{\mathrm{Max[Tr(KT)]}}{n_\mathrm{occupied\ bands}}} + +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. + +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. + + 1. The diagonal elements of :math:`KT`. + 2. The diagonal elements of :math:`S^{-1}T`. + 3. The diagonal elements of :math:`T`. + +Keywords +======== + +- ``precond_recip`` [Basic, bool, default ``F``\ ] Turn on reciprocal space + kinetic energy preconditioning? [Incompatible with ``precond_real``] + +- ``precond_real`` [Basic, bool, default ``T``\ ] Turn on real space + kinetic energy preconditioning? [Incompatible with ``precond_recip`` and + automatic :math:`k_0` mode.] + +- ``precond_scheme`` [Basic, string, default ``TETER``\ ] The type of kinetic + energy preconditioning scheme to use. Options are: `BG`, `MAURI`, `TETER` or + `NONE`. + +- ``k_zero`` [Basic, physical 1/Bohr, default ``3.0``\ ] The :math:`k_0` value + used in the kinetic energy preconditioning. If set to a negative value, + ONETEP will automatically calculate the :math:`k_0` value based on the average + kinetic energy of the system. + +- ``precond_array`` [Basic, bool, default ``F``\ ] Turn on NGWF-specific + preconditioning where each NGWF has its own :math:`k_0` value based on its own kinetic + energy expectation value? (requires ``k_zero`` to be negative). + +- ``precond_array_type`` [Basic, string, default ``KT``\ ] The type of kinetic + energy to use for NGWF-specific preconditioning. Options are: `KT`, `INVST`, + and `T`. (requires ``precond_array`` to be ``T``).