LMAXFOCKAE: Difference between revisions

Latest revision as of 13:46, 22 July 2026

Default: LMAXFOCKAE	= -1	DFT, Hartree-Fock
	= 4	post-DFT methods

Description: Specifies the maximum spherical angular momentum quantum number ([math]\displaystyle{ L }[/math]) up to which augmentation charges are accurately restored on the plane-wave grid. This parameter controls the quality of shape restoration for the PAW method.

In the PAW method, the difference between the charge density of the all-electron partial waves [math]\displaystyle{ \phi_n }[/math] and the pseudo partial waves [math]\displaystyle{ \tilde \phi_n }[/math]

[math]\displaystyle{ Q_{nm}({\mathbf r})= \phi^*_n({\mathbf r})\phi_m({\mathbf r}) - \tilde \phi^*_n({\mathbf r})\tilde \phi_m({\mathbf r}) }[/math]

is usually treated on spherical grids centered at each atom (one-center terms inside the PAW spheres, see PAW method method and more detailed description for LMAXFOCK). To describe long-range electrostatic effects, the moments of the differences of the all-electron and pseudo charge density also need to be added on the plane wave grid (compensation density, see PAW method). These compensation charges exactly restore the moments of the all-electron density on the plane wave grid. For the Fock exchange the maximum L quantum number up to which the augmentation is done is controlled by LMAXFOCK.

For GW, RPA, and post-DFT methods, the one-center terms are, however, presently not implemented, which can cause sizable errors, particularly for 3d and (to a lesser extent) 2p, 4d, and 5d elements. To correct for this error, an alternative treatment is implemented on the plane-wave grid for the exchange and correlation contributions, allowing for accurate restoration of the all-electron densities.

This improved treatment — termed shape restoration — is available for exchange as well as many-body correlation contributions. More details on shape restoration are explained in Ref. ^[1] and ^[2].

Shape restoration allows restoration of the all-electron densities accurately already on the plane-wave grid by specifying the tags LMAXFOCKAE and NMAXFOCKAE. This accurate augmentation charge [math]\displaystyle{ \hat n }[/math] is calculated for the total orbital and angular momentum quantum numbers [math]\displaystyle{ L }[/math] (up to LMAXFOCKAE) and [math]\displaystyle{ M }[/math] using shape-restoring radial functions [math]\displaystyle{ \Delta g_L(r) }[/math] with coefficients [math]\displaystyle{ c^L_{nm} }[/math] to be determined:

[math]\displaystyle{ \hat n=\sum_{LM\atop n,m}\rho_{LM}\!\left[q^{LM}_{nm}Y_{LM}(\Omega)+c^L_{nm}\,\Delta g_L(r)Y_{LM}(\Omega)\right] }[/math]

where [math]\displaystyle{ Y_{LM}(\Omega) }[/math] are the spherical harmonics and [math]\displaystyle{ q^{LM}_{nm} }[/math] are the moments of the charge difference.

NMAXFOCKAE controls how accurately this compensation is performed by specifying the maximum expansion order of spherical Bessel functions [math]\displaystyle{ j_L }[/math] with carefully chosen coefficients [math]\displaystyle{ \alpha_{\beta L} }[/math] and [math]\displaystyle{ q_{\beta L} }[/math] (cf. Appendix of Ref. ^[2] for details).

[math]\displaystyle{ \;\Delta g_L(r)=\sum_{\beta=1}^{NMAXFOCKAE}\alpha_{\beta L}\, j_L\!\left(q_{\beta L}\, r\right) }[/math]

Mind: This tag generally only applies to the Fock-exchange and many-body perturbation theory (MBPT) (GW, RPA, MP2, etc). The default for DFT and Hartree-Fock, LMAXFOCKAE = -1, restores only the moments of the all-electron charge densities on the plane-wave grid. For Hartree-Fock, the setting is very precise since the one-center terms are implemented in radial grids as for DFT.

Recommendations

Element-Dependent

The setting for LMAXFOCKAE should be chosen based on the elements in the calculation:

s and p elements: LMAXFOCKAE = 2
d elements: LMAXFOCKAE = 4 (a d electron can create charge densities with L-quantum numbers up to 4)
f elements: LMAXFOCKAE = 6 may be required - test for each case

The general rule is to set LMAXFOCKAE to approximately twice the maximum l quantum number found in the POTCAR file.

General

Setting LMAXFOCKAE = 4 (or larger) forces an accurate treatment for charge augmentation on the plane-wave grid. This can be selected even in Hartree-Fock-type calculations, but causes some additional noise.
If no accurate augmentation is desired set LMAXFOCKAE = -1, which will reduce the noise in the correlation energies.
For DFT calculations, the exact one-center terms are implemented. This means shape restoration is not required and should not change the results. For post-DFT calculations, shape restoration significantly improves accuracy.

Relationship with NMAXFOCKAE

LMAXFOCKAE and NMAXFOCKAE are strongly coupled. It is vital to use consistent settings for both when comparing energy differences.

NMAXFOCKAE = 1 and LMAXFOCKAE ≥ 0: Charge density is restored up to approximately 150 eV (controlled by QMAXFOCKAE).
NMAXFOCKAE = 2 and LMAXFOCKAE ≥ 0: Charge density is restored up to approximately 400 eV.

Important: NMAXFOCKAE = 2 is for very accurate augmentation on the plane-wave grid. Use NMAXFOCKAE = 2 only with care, as it can result in very noisy data for coarse FFT grids.

References

[shishkin:prb:2006-1] M. Shishkin and G. Kresse, Phys. Rev. B 74, 035101 (2006).

[unzog:prb:2022-2] M. Unzog, A. Tal, G. Kresse, X-ray absorption using the projector augmented-wave method and the Bethe-Salpeter equation, Phys. Rev. B 106, 155133 (2022).

[1]

[2]

@@ Line 1: / Line 1: @@
-{{TAGDEF|LMAXFOCKAE|[integer]|-1}}
+{{TAGDEF|LMAXFOCKAE|[integer]}}
-{{DEF|ICHARG|2|if {{TAG|ISTART}}{{=}}0|0|else}}
-{{TAGDEF|NMAXFOCKAE|0{{!}}1{{!}}2}}
+{{DEF|LMAXFOCKAE|-1|DFT, Hartree-Fock|4|post-DFT methods}}
-{{DEF|NMAXFOCKAE|0|density functional theory|1|post DFT methods}}
+Description: Specifies the maximum spherical angular momentum quantum number (<math>L</math>) up to which augmentation charges are accurately restored on the plane-wave grid. This parameter controls the quality of shape restoration for the [[Projector-augmented-wave_formalism|PAW method]].
+----
+In the [[Projector-augmented-wave_formalism|PAW method]], the difference between the charge density of the all-electron partial waves <math>\phi_n</math> and the pseudo partial waves <math>\tilde \phi_n</math>
+<math>
+Q_{nm}({\mathbf r})= \phi^*_n({\mathbf r})\phi_m({\mathbf r})  - \tilde \phi^*_n({\mathbf r})\tilde \phi_m({\mathbf r})
+</math>
+is usually treated on spherical grids centered at each atom
+(one-center terms inside the PAW spheres, see [[Projector-augmented-wave_formalism|PAW method]] method and more detailed description for {{TAG|LMAXFOCK}}).  To describe long-range electrostatic effects, the ''moments'' of the differences of the all-electron and pseudo charge density also need to be added on the plane wave grid (compensation density, see [[Projector-augmented-wave_formalism|PAW method]]). These compensation charges exactly restore the moments of the all-electron density on the plane wave grid. For the Fock exchange the maximum ''L'' quantum number up to which the augmentation is done is controlled by {{TAG|LMAXFOCK}}.
+For [[GW approximation of Hedin's equations|GW]], [[ACFDT/RPA calculations|RPA]], and [[:Category:Many-body perturbation theory|post-DFT]] methods, the one-center terms are, however, presently not implemented, which can cause sizable errors, particularly for 3''d'' and (to a lesser extent) 2''p'', 4''d'', and 5''d'' elements. To correct for this error, an alternative treatment is implemented on the plane-wave grid for the exchange and correlation contributions, allowing for accurate restoration of the all-electron densities.
+This improved treatment — termed ''shape restoration'' — is available for exchange as well as many-body correlation contributions. <!--For exchange, the exact one-center terms are also implemented (cf. {{TAG|LFOCKSTD}}); this means shape restoration is not required and should not change the results.--> More details on shape restoration are explained in Ref. {{cite|shishkin:prb:2006}} and {{cite|unzog:prb:2022}}.
+Shape restoration allows restoration of the all-electron densities accurately already on the plane-wave grid by specifying the tags {{TAG|LMAXFOCKAE}} and {{TAG|NMAXFOCKAE}}. This accurate augmentation charge <math>\hat n</math> is calculated for the total orbital and angular momentum quantum numbers <math>L</math> (up to {{TAG|LMAXFOCKAE}}) and <math>M</math> using shape-restoring radial functions <math>\Delta g_L(r)</math> with coefficients <math>c^L_{nm}</math> to be determined:
-Description: {{TAG|LMAXFOCKAE}} and {{TAG|LMAXFOCKAE}} describes the maximum angular momentum quantum number ''l'' and the number of channels for an "accurate" augmentation of charge densities in Hartree-Fock type routines.
-----
-In the PAW method the difference between the charge density of the all-electron partial waves and
-the pseudo partial waves
 <math>
-Q_{\alpha\beta}(r)= \phi^*_\alpha(r)\phi_\beta(r)  - \tilde \phi^*_\alpha(r)\tilde \phi_\beta(r)
+\hat n=\sum_{LM\atop n,m}\rho_{LM}\!\left[q^{LM}_{nm}Y_{LM}(\Omega)+c^L_{nm}\,\Delta g_L(r)Y_{LM}(\Omega)\right]
 </math>
-is usually restored on spherical grids centered at each atom
-(one-center terms inside the PAW spheres). To describe long range electrostatic terms, the
-the ''moments'' of the differences of the all-electron and pseudo charge density are also
-restored on the plane wave grid up to a certain ''l'' quantum number (see {{TAG|LMAXFOCK}}).
-For the RPA, GW, and most post DFT methods, the one-center terms are presently,
+where <math>Y_{LM}(\Omega)</math> are the spherical harmonics and <math>q^{LM}_{nm}</math> are the moments of the charge difference.
-however, not implemented. Depending on the material, this can cause sizable errors
-in particular for 3d and (to a lesser extent) 2p, 4d and 5d elements.
-To correct for this error, an alternative treatment is implemented
-on the plane wave grid. This  allows to restore the ''shape'' of the charge density difference accurately on the plane wave grid, using the flags {{TAG|LMAXFOCKAE}} and {{TAG|NMAXFOCKAE}}.
-To achieve this, <math> Q_{\alpha\beta}(r) </math> is Fourier transformed
+{{TAG|NMAXFOCKAE}} controls how accurately this compensation is performed by specifying the maximum expansion order of spherical Bessel functions <math>j_L</math> with carefully chosen coefficients <math>\alpha_{\beta L}</math> and <math>q_{\beta L}</math> (cf. Appendix of Ref. {{cite|unzog:prb:2022}} for details).
-to reciprocal space <math> Q_{\alpha\beta}(q) </math> and then expanded
-in a set of orthogonal functions localized at each atomic site.
+<math>
+\;\Delta g_L(r)=\sum_{\beta=1}^{NMAXFOCKAE}\alpha_{\beta L}\, j_L\!\left(q_{\beta L}\, r\right)
+</math>
+{{NB|mind|This tag generally only applies to the Fock-exchange and [[:Category:Many-body perturbation theory|many-body perturbation theory]] (MBPT) (GW, RPA, [[MP2]], etc). The default for DFT and Hartree-Fock, {{TAG|LMAXFOCKAE|-1}}, restores only the moments of the all-electron charge densities on the plane-wave grid. For Hartree-Fock, the setting is very precise since the one-center terms are implemented in radial grids as for DFT.
+}}
-If the {{TAG|NMAXFOCKAE}}=0 (the default for DFT and Hartree-Fock calculations), only the moment and of the all-electron charge density is restored on the plane wave grid. This setting is exact for density functional theory, Hartree-Fock as well
+== Recommendations ==
-as hybrid functionals, since the one-center terms are implemented.
+=== Element-Dependent ===
+The setting for {{TAG|LMAXFOCKAE}} should be chosen based on the elements in the calculation:
+* '''''s'' and ''p'' elements''': {{TAG|LMAXFOCKAE|2}}
+* '''''d'' elements''': {{TAG|LMAXFOCKAE|4}} (a ''d'' electron can create charge densities with L-quantum numbers up to 4)
+* '''''f'' elements''': {{TAG|LMAXFOCKAE|6}} may be required - test for each case
-If the {{TAG|NMAXFOCKAE}}=1 is set, the moments of the all-electron charge density are stored on the plane wave grid. Furthermore, the all-electron charge density is restored up to  a typical plane wave energy of 140 eV. This setting yields very accurate results for post DFT methods (MP2, RPA, GW, etc.) for most sp bonded materials.  {{TAG|LMAXFOCKAE}} can be used to specify the maximum spherical (l) quantum number up
+The general rule is to set {{TAG|LMAXFOCKAE}} to approximately twice the maximum ''l'' quantum number found in the {{FILE|POTCAR}} file.
-to which this more accurate treatment is used. The default for {{TAG|LMAXFOCKAE}} is 4.
-If {{TAG|NMAXFOCKAE}}=2 is set, the charge density is restored accurately on the plane wave grid up to a typical plane wave energies of 380 eV. As before,  {{TAG|LMAXFOCKAE}} can be used to specify the maximum spherical (l) quantum number up
+=== General ===
-to which this more accurate treatment is used.  {{TAG|NMAXFOCKAE}}=2 yields very accurate results for
+* Setting {{TAG|LMAXFOCKAE|4}} (or larger) forces an accurate treatment for charge augmentation on the plane-wave grid. This can be selected even in Hartree-Fock-type calculations, but causes some additional noise.
-post DFT methods (MP2, RPA, GW) even for difficult 3d elements. For RPA and MP2 total energy calculations, differences between {{TAG|NMAXFOCKAE}}=1 and {{TAG|NMAXFOCKAE}}=2 are usually tiny for total energy differences. Since the absolute correlation energies might change, it is vital to use the same setting for
+*If no accurate augmentation is desired set {{TAG|LMAXFOCKAE|-1}}, which will reduce the noise in the correlation energies.
-{{TAG|NMAXFOCKAE}} and {{TAG|LMAXFOCKAE}}, if energy differences are calculated.
+* For DFT calculations, the exact one-center terms are implemented. This means shape restoration is not required and should not change the results. For post-DFT calculations, shape restoration significantly improves accuracy.
-For GW calculations, increasing  {{TAG|NMAXFOCKAE}}=1 to {{TAG|NMAXFOCKAE}}=2 might change QP energies by 100-200 meV for 3d and late 4d and 5d elements.
+=== Relationship with NMAXFOCKAE ===
+{{TAG|LMAXFOCKAE}} and {{TAG|NMAXFOCKAE}} are strongly coupled. It is vital to use consistent settings for both when comparing energy differences.
+* {{TAG|NMAXFOCKAE|1}} and {{TAG|LMAXFOCKAE|0|op=≥}}: Charge density is restored up to approximately 150 eV (controlled by {{TAG|QMAXFOCKAE}}).
+* {{TAG|NMAXFOCKAE|2}} and {{TAG|LMAXFOCKAE|0|op=≥}}: Charge density is restored up to approximately 400 eV.
+{{NB|important|{{TAG|NMAXFOCKAE|2}} is for very accurate augmentation on the plane-wave grid. Use {{TAG|NMAXFOCKAE|2}} only with care, as it can result in very noisy data for coarse FFT grids.|:}}
-If  {{TAG|NMAXFOCKAE}} is used, the setting for {{TAG|LMAXFOCKAE}} should be also checked. Generally, it suffices to set {{TAG|LMAXFOCKAE}} to twice the maximum ''l'' quantum number found in the {{FILE|POTCAR}} file.
+== Related tags and articles ==
-For instance for sp elements, {TAG|LMAXFOCKAE}} = 2 suffices. For d elements, {TAG|LMAXFOCKAE}} = 4 suffices
+{{TAG|NMAXFOCKAE}}, {{TAG|LMAXFOCK}}, {{TAG|QMAXFOCKAE}}, {{TAG|LFOCKAEDFT}}, {{TAG|LFOCKSTD}}
-(a d electron can create a density with l-quantum number of 4), whereas for f elements, users
-should test whether  {TAG|LMAXFOCKAE}} = 4 is required.
+{{sc|LMAXFOCKAE|Examples|Examples that use this tag}}
-== Related Tags and Sections ==
+== References ==
-{{TAG|LMAXFOCK}}
-----
-[[The_VASP_Manual|Contents]]
-[[Category:INCAR]][[Category:Hybrids]]
+[[Category:INCAR tag]]
+[[Category:ACFDT]]
+[[Category:Low-scaling GW and RPA]]
+[[Category:Exchange-correlation functionals]]
+[[Category:Hybrid functionals]]
+[[Category:Many-body perturbation theory]]
+[[Category:GW]]