From 2b46c07d8314e5a50f2dd9ef264e4e1b2276b19f Mon Sep 17 00:00:00 2001 From: Chengcheng Xiao Date: Wed, 10 Dec 2025 23:35:28 +0000 Subject: [PATCH 1/3] Add documentation for rec-space kenetic energy preconditioning. --- index_ground_state.rst | 1 + recip_precond.rst | 82 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 recip_precond.rst 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..288c3db --- /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 use 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=\braket{\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 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 kintetic energy to use for the +upreconditioning 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:`k0` 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, float 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 k0 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 k0 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``). From 2516e4f839a417061ba5035045b5f71bb6f18077 Mon Sep 17 00:00:00 2001 From: Chengcheng Xiao Date: Wed, 10 Dec 2025 23:45:12 +0000 Subject: [PATCH 2/3] Update format for latexpdf print. Update conf with new version 8.0.0 --- conf.py | 4 ++-- recip_precond.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) 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/recip_precond.rst b/recip_precond.rst index 288c3db..c3c3f70 100644 --- a/recip_precond.rst +++ b/recip_precond.rst @@ -19,7 +19,7 @@ where, .. math:: x=\frac{\left(\hbar^2|\mathbf{k}+\mathbf{G}|^2\right) / 2 m}{T_i^m} -and :math:`T_i^m=\braket{\psi_i^m\left|\left(-\hbar^2 / 2 m\right) \nabla^2\right| \psi_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 From fd8c513f59276cc1abbf483de394f1e7288fc029 Mon Sep 17 00:00:00 2001 From: Chengcheng Xiao Date: Thu, 18 Dec 2025 21:05:51 +0800 Subject: [PATCH 3/3] Fix formatting issues. --- recip_precond.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/recip_precond.rst b/recip_precond.rst index c3c3f70..00fd54b 100644 --- a/recip_precond.rst +++ b/recip_precond.rst @@ -5,7 +5,7 @@ Kinetic energy preconditioning in ONETEP :Author: Chengcheng Xiao :Date: Dec 2025 -ONETEP at the moment, by default use a modified Teter reciprocal +ONETEP at the moment, by default uses a modified Teter reciprocal preconditioning. `The original Teter reciprocal preconditioning function `__ @@ -14,7 +14,7 @@ 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, +where .. math:: x=\frac{\left(\hbar^2|\mathbf{k}+\mathbf{G}|^2\right) / 2 m}{T_i^m} @@ -30,8 +30,8 @@ modified to be: and :math:`k_0` is a manually specified number. -Automatic selection of k_0 -========================== +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 @@ -47,8 +47,8 @@ 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 kintetic energy to use for the -upreconditioning for each NGWF. +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`. @@ -62,21 +62,21 @@ Keywords - ``precond_real`` [Basic, bool, default ``T``\ ] Turn on real space kinetic energy preconditioning? [Incompatible with ``precond_recip`` and - automatic :math:`k0` mode.] + automatic :math:`k_0` mode.] -- ``precond_scheme`` [Basic string, default ``TETER``\ ] The type of kinetic +- ``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, float 1/Bohr, default ``3.0``\ ] The :math:`k_0` value +- ``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 k0 value based on the average + 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 k0 value based on its own kinetic + 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 +- ``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``).