NMAXFOCKAE: Difference between revisions

Revision as of 05:26, 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 6 Å^-1, which corresponds to a plane-wave energy of approximately 140 eV.
NMAXFOCKAE = 2: two functions per [math]\displaystyle{ L }[/math], matched at 5 and 10 Å^-1, corresponding to approximately 95 eV and 380 eV.

These wave vectors are the points at which the density is fitted, not a guarantee of the accuracy reached at a given cutoff. They can be changed with QMAXFOCKAE, which replaces the first value; the second follows at twice the first.

Only the values 1 and 2 are accepted. 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}} determines the maximum order of expansion for augmentation charges used in [[LMAXFOCKAE|shape restoration]] for the [[Projector-augmented-wave_formalism|PAW method]].
+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]].
 ----
-{{TAG|NMAXFOCKAE}} controls how accurately this augmentation is performed by specifying the maximum expansion order. It controls the plane-wave cutoff up to which accurate charge densities are restored on the plane-wave grid. Shape restoration is only accurate up to a certain plane-wave cutoff, typically about 150 eV for {{TAG|NMAXFOCKAE|1}}, and 400 eV for {{TAG|NMAXFOCKAE|2}}.
+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:
-{{NB|important|Shape restoration is more fully documented in the {{TAG|LMAXFOCKAE}} page. Additionally, see Ref. {{cite|shishkin:prb:2006}} and {{cite|unzog:prb:2022}}.}}
-{{NB|mind|This tag generally only applies to the Fock-exchange and [[:Category:Many-body_perturbation_theory|many-body perturbation theory]] (MBPT) methods ([[GW approximation of Hedin's equations|GW]], [[ACFDT/RPA calculations|RPA]], [[MP2]], etc.).}}
+* {{TAG|NMAXFOCKAE|1}}: one function per <math>L</math>, matched at 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 5 and 10 Å<sup>-1</sup>, corresponding to approximately 95 eV and 380 eV.
+These wave vectors are the points at which the density is fitted, not a guarantee of the accuracy reached at a given cutoff. They can be changed with {{TAG|QMAXFOCKAE}}, which replaces the first value; the second follows at twice the first.
+Only the values 1 and 2 are accepted. 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}} is sufficient in most cases and provides a good balance between accuracy and computational cost. It predicts very accurate energy differences and quite accurate quasiparticle energies.
-*{{TAG|NMAXFOCKAE|2}} should be used with great caution. Specifically, noise and egg-box effects for coarse FFT grids are introduced as {{TAG|NMAXFOCKAE}} is increased. Use this tag only after extensive tests and verification that the increased accuracy is needed for your application. It yields very accurate results for post-DFT methods (MP2, RPA, GW) even for difficult 3''d'' elements.
+{{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.
-**For [[GW approximation of Hedin's equations|GW calculations]], increasing from {{TAG|NMAXFOCKAE|1}} to {{TAG|NMAXFOCKAE|2}} might change quasiparticle energies by 100-200 meV for 3''d'' and late 4''d'' and 5''d'' elements.
-**For [[ACFDT/RPA calculations|RPA]] and [[MP2|MP2]] total energy calculations, differences between {{TAG|NMAXFOCKAE|1}} and {{TAG|NMAXFOCKAE|2}} are usually small for total energy differences. {{NB|mind|Since absolute correlation energies might change, it is vital to use consistent settings for {{TAG|NMAXFOCKAE}} and {{TAG|LMAXFOCKAE}}, if energy differences are calculated. Please check whether the VASP default setting for {{TAG|LMAXFOCKAE}} suffices ({{FILE|OUTCAR}} file). Use this setting only with care, as it can result in very noisy data for coarse FFT grids.|::}}
+{{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.
+Two specific expectations from the literature:
+* 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}}.
+* 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.
 == Related tags and articles ==
-{{TAG|LMAXFOCKAE}}, {{TAG|LMAXFOCK}}, {{TAG|QMAXFOCKAE}}, {{TAG|LFOCKAEDFT}}, {{TAG|LFOCKSTD}}
+{{TAG|LMAXFOCKAE}}, {{TAG|LMAXFOCK}}, {{TAG|QMAXFOCKAE}}, {{TAG|LFOCKAEDFT}}, {{TAG|LFOCKSTD}}, [[Projector-augmented-wave formalism]]
-{{sc|NMAXFOCKAE|Examples|Examples that use this tag}}
+{{sc|NMAXFOCKAE|Howto|Workflows that use this tag}}
 == References ==
+<references/>
 [[Category:INCAR tag]]
 [[Category:ACFDT]]