NMAXFOCKAE: Difference between revisions

Latest revision as of 05:51, 9 September 2026

NMAXFOCKAE = 1|2
Default: NMAXFOCKAE = 1

Description: Sets the number of shape-restoring functions used for each angular momentum quantum number [math]\displaystyle{ L }[/math] in shape restoration.

In shape restoration, radial functions with vanishing multipole moment are added to the PAW compensation charge for each angular momentum quantum number [math]\displaystyle{ L }[/math]. LMAXFOCKAE sets the maximum [math]\displaystyle{ L }[/math]; NMAXFOCKAE sets how many functions are used per [math]\displaystyle{ L }[/math], and thereby the wave vectors at which the all-electron density is matched:

NMAXFOCKAE = 1: one function per [math]\displaystyle{ L }[/math], matched at QMAXFOCKAE (default 6 Å^-1, which corresponds to a plane-wave energy of approximately 140 eV).
NMAXFOCKAE = 2: two functions per [math]\displaystyle{ L }[/math], matched at QMAXFOCKAE and twice QMAXFOCKAE (default 5 and 10 Å^-1, corresponding to approximately 95 eV and 380 eV).

The wave vectors QMAXFOCKAE are the points at which the density is fitted, not a guarantee of the accuracy reached at a given cutoff.

NMAXFOCKAE only accepts the values 1 and 2. Values outside that range are corrected to the nearest allowed one, so a larger number does not give a finer expansion.

Mind: Whenever LMAXFOCKAE = -1 is set — the default for DFT and Hartree-Fock — shape restoration is inactive and NMAXFOCKAE has no effect. Shape restoration applies only to the Fock exchange and to many-body perturbation theory, i.e., GW, RPA and MP2.

Important: The total energies of calculations that differ in NMAXFOCKAE and/or LMAXFOCKAE cannot be compared.

Recommendations

NMAXFOCKAE = 1, the default, is sufficient in most cases and balances accuracy against computational cost. Refs. ^[1] and ^[2] report accurate energy differences and quasiparticle energies at this setting.

NMAXFOCKAE = 2 is reported to give very accurate results for post-DFT methods, including for the 3d elements where the one-center error is largest^[2]. It is not free: the noise and the egg-box effects grow with NMAXFOCKAE, and two shape-restoring functions per [math]\displaystyle{ L }[/math] need a fine FFT grid. Set NGX, NGY and NGZ explicitly when using it. VASP issues an alert to that effect whenever two functions are requested. We recommend using it only after tests that establish the higher accuracy is needed for your application.

Two specific expectations from the literature:

For GW calculations, going from NMAXFOCKAE = 1 to NMAXFOCKAE = 2 may shift quasiparticle energies by 100 to 200 meV for 3d and late 4d and 5d elements^[2].
For RPA and MP2 total energies, the two settings usually differ little in energy differences, even though the absolute correlation energies change^[2].

The two tags are coupled: see LMAXFOCKAE for the consistency requirement that applies when energy differences are compared, and for how to read both values back from the OUTCAR file.

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|NMAXFOCKAE|1{{!}}2|1}}
-Description: {{TAG|NMAXFOCKAE}} and {{TAG|LMAXFOCKAE}} determine whether
+Description: Sets the number of shape-restoring functions used for each angular momentum quantum number <math>L</math> in [[Projector-augmented-wave formalism#Shape restoration|shape restoration]].
-the overlap densities in the Fock exchange and correlated wave function methods are accurately reconstructed on the plane wave grid. This flag generally only applies to the Fock-exchange part as well as many-body
-post DFT methods (GW, RPA, MP2, etc.).  Details can be found in the section {{TAG|LMAXFOCKAE}}.
 ----
+In [[Projector-augmented-wave formalism#Shape restoration|shape restoration]], radial functions with vanishing multipole moment are added to the PAW compensation charge for each angular momentum quantum number <math>L</math>. {{TAG|LMAXFOCKAE}} sets the maximum <math>L</math>; {{TAG|NMAXFOCKAE}} sets how many functions are used per <math>L</math>, and thereby the wave vectors at which the all-electron density is matched:
+* {{TAG|NMAXFOCKAE|1}}: one function per <math>L</math>, matched at {{TAG|QMAXFOCKAE}} (default 6 Å<sup>-1</sup>, which corresponds to a plane-wave energy of approximately 140 eV).
+* {{TAG|NMAXFOCKAE|2}}: two functions per <math>L</math>, matched at {{TAG|QMAXFOCKAE}} and twice {{TAG|QMAXFOCKAE}} (default 5 and 10 Å<sup>-1</sup>, corresponding to approximately 95 eV and 380 eV).
-== Related Tags and Sections ==
+The wave vectors {{TAG|QMAXFOCKAE}} are the points at which the density is fitted, not a guarantee of the accuracy reached at a given cutoff.
-{{TAG|LMAXFOCK}} {{TAG|LMAXFOCKAE}}
-----
-[[The_VASP_Manual|Contents]]
-[[Category:INCAR]][[Category:Hybrids]]
+{{TAG|NMAXFOCKAE}} only accepts the values 1 and 2. Values outside that range are corrected to the nearest allowed one, so a larger number does not give a finer expansion.
+{{NB|mind|Whenever {{TAG|LMAXFOCKAE|-1}} is set — the default for DFT and Hartree-Fock — shape restoration is inactive and {{TAG|NMAXFOCKAE}} has no effect. Shape restoration applies only to the Fock exchange and to [[:Category:Many-body perturbation theory|many-body perturbation theory]], i.e., [[GW approximation of Hedin's equations|GW]], [[ACFDT/RPA calculations|RPA]] and [[MP2]].}}
+{{NB|important|The total energies of calculations that differ in {{TAG|NMAXFOCKAE}} and/or {{TAG|LMAXFOCKAE}} cannot be compared.}}
+== Recommendations ==
-----
+{{TAG|NMAXFOCKAE|1}}, the default, is sufficient in most cases and balances accuracy against computational cost. Refs. {{cite|shishkin:prb:2006}} and {{cite|unzog:prb:2022}} report accurate energy differences and quasiparticle energies at this setting.
-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)
-</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 usually
-also added on the plane wave grid up to a certain l quantum number (see {{TAG|LMAXFOCK}}).
-These augmentation charges restore the moments of the all-electron density on the plane wave
-grid.
-For the RPA, GW, and most post DFT methods, the one-center terms are presently,
+{{TAG|NMAXFOCKAE|2}} is reported to give very accurate results for post-DFT methods, including for the 3''d'' elements where the one-center error is largest{{cite|unzog:prb:2022}}. It is not free: the noise and the egg-box effects grow with {{TAG|NMAXFOCKAE}}, and two shape-restoring functions per <math>L</math> need a fine FFT grid. Set {{TAG|NGX}}, {{TAG|NGY}} and {{TAG|NGZ}} explicitly when using it. VASP issues an alert to that effect whenever two functions are requested. We recommend using it only after tests that establish the higher accuracy is needed for your application.
-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 all-electron densities accurately on the plane wave grid
-instead of the one-center grids by specifying the flags {{TAG|LMAXFOCKAE}} and {{TAG|NMAXFOCKAE}}.
-To achieve this improved treatment on the plane wave grid, <math> Q_{\alpha\beta}(r) </math> is Fourier transformed  to reciprocal space <math> Q_{\alpha\beta}(q) </math> and then expanded
+Two specific expectations from the literature:
-in a set of orthogonal functions localized at each atomic site. These augmentation charges
+* For [[GW approximation of Hedin's equations|GW calculations]], going from {{TAG|NMAXFOCKAE|1}} to {{TAG|NMAXFOCKAE|2}} may shift quasiparticle energies by 100 to 200 meV for 3''d'' and late 4''d'' and 5''d'' elements{{cite|unzog:prb:2022}}.
-are then added to the pseudo charge densities on the plane wave grid.
+* For [[ACFDT/RPA calculations|RPA]] and [[MP2]] total energies, the two settings usually differ little in energy ''differences'', even though the absolute correlation energies change{{cite|unzog:prb:2022}}.
+The two tags are coupled: see {{TAG|LMAXFOCKAE}} for the consistency requirement that applies when energy differences are compared, and for how to read both values back from the {{FILE|OUTCAR}} file.
-For {{TAG|LMAXFOCKAE}}=-1 (the default for DFT and Hartree-Fock calculations), only the moments of the all-electron charge densities are restored on the plane wave grid. This setting is exact for Hartree-Fock
+== Related tags and articles ==
-since the one-center terms are implemented.
+{{TAG|LMAXFOCKAE}}, {{TAG|LMAXFOCK}}, {{TAG|QMAXFOCKAE}}, {{TAG|LFOCKAEDFT}}, {{TAG|LFOCKSTD}}, [[Projector-augmented-wave formalism]]
-If {{TAG|LMAXFOCKAE}} is set to value larger than -1 (and {{TAG|NMAXFOCKAE}}=1), not only the moments of the all-electron charge density are restored, but also 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}} is used to specify the maximum spherical (l) quantum number up
+{{sc|NMAXFOCKAE|Howto|Workflows that use this tag}}
-to which this more accurate treatment is used. The default is {{TAG|LMAXFOCKAE}}=4, for post DFT methods.
-If no accurate augmentation is desired by the user, simply set {{TAG|LMAXFOCKAE}}=-1 in the INCAR file.
-If {{TAG|LMAXFOCKAE}} is set to value larger than -1 and {{TAG|NMAXFOCKAE}}=2, 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
+== References ==
-to which this more accurate treatment is used.  {{TAG|NMAXFOCKAE}}=2 yields very accurate results for
+<references/>
-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
-{{TAG|NMAXFOCKAE}} and {{TAG|LMAXFOCKAE}}, if energy differences are calculated.
-For GW calculations, increasing  {{TAG|NMAXFOCKAE}} from 1 to 2 might change QP energies by 100-200 meV for 3d and late 4d and 5d elements.
-The setting for {{TAG|LMAXFOCKAE}} should be also considered carefully. Generally, it suffices to set {{TAG|LMAXFOCKAE}} to twice the maximum ''l'' quantum number found in the {{FILE|POTCAR}} file.
-For instance for sp elements, {{TAG|LMAXFOCKAE}} = 2 suffices. For d elements, {{TAG|LMAXFOCKAE}} = 4 suffices
-(a d electron can create charge densities with ''l''-quantum numbers up to 4), whereas for f elements, users
-should test whether  {{TAG|LMAXFOCKAE}} = 6 is required.
-In summary, usefully manual setting of {{TAG|NMAXFOCKAE}}  and {{TAG|LMAXFOCKAE}} are:
-*  {{TAG|LMAXFOCKAE}}=-1, to switch off the accurate augmentation altogether
-* {{TAG|LMAXFOCKAE}}=4 (or larger) to force an accurate treatment for the HF part even in Hartree-Fock calculations
-* {{TAG|NMAXFOCKAE}}=2, to select the very accurate augmentation. Please check whether the VASP default setting for {{TAG|LMAXFOCKAE}} suffices (OUTCAR file).
-== Related Tags and Sections ==
-{{TAG|LMAXFOCK}} {{TAG|QMAXFOCKAE}}
-----
-[[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]]