doc : update session on scf convergence (#1313)

* doc : update for VdW correction

* doc : fix bug in index.rst

* doc : add another layer in example/vdw

* doc : add link for vdw example

* doc : add part for XC functionals

* docs : update deeph and out_mat_XX

* docs : update session for converging SCF

Co-authored-by: wenfei-li <liwenfei@gmail.com>

docs/advanced/interface/deeph.md

@@ -26,4 +26,4 @@ For that purpose, in `INPUT` file we need to make the following specification of
 calculation get_S
 ```
 
-A file named `SR.csr` will be generated in te working directory, which contains the overlap matrix.
+A file named `SR.csr` will be generated in the working directory, which contains the overlap matrix.

docs/advanced/scf/converge.md

@@ -1,5 +1,25 @@
 # Converging SCF
 
+As in any non-linear systems, numerical instabilities during SCF iterations may lead to nonconvergence. In ABACUS, we offer the following options to facilitate SCF convergence.
+
 ## Charge Mixing
 
-## Smearing
+By mixing the electron density with that obtained from previous steps, numerical instabilities can be ameliorated. ABACUS offers several mixing schemes, and users may make a selection by adjusting the [mixing_type](../input_files/input-main.md#mixingtype) keyword in INPUT file.
+
+For each of the mixing types, we also provide variables for controlling relevant parameters, including `mixing_beta`, `mixing_ndim`, and `mixing_gg0`.
+
+The default choice is `pulay`, which should work fine in most cases. If convergence issue arises in metallic systems, inclusion of Kerker preconditioning may be helpful, namely, to use `kerker` or `pulay-kerker` mixing methods.
+
+A large `mixing_beta` means a larger change in electron density for each SCF step. For well-behaved systems, a larger `mixing_beta` leads to faster convergence. However, for some difficult cases, a smaller `mixing_beta` is preferred to avoid numerical instabilities.
+
+An example showcasing different charge mixing methods can be found in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/charge_mixing/pw_Al). Four INPUT files are provided, with description given in README.
+
+## Smearing
+
+Thermal smearing is an efficient tool for accelerating SCF convergence by allowing fractional occupation of molecular orbitals near the band edge. It is important for metallic systems.
+
+In ABACUS, we provide a few smearing methods, which can be controlled using the keyword [smearing_method](../input_files/input-main.md#smearingmethod). We also provide keyword `smearing_sigma` or `smearing_sigma_temp` to control the energy range of smearing. A larger value of smearing sigma leads to a more diffused occupation curve.
+
+> Note : The two keywords `smearing_sigma` and `smearing_sigma_temp` should not be used concurrently.
+
+We provide an example showing the importance of smearing in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/smearing/lcao_fe). Two INPUT fiels rae provided, with description given in README.

docs/input-main.md

@@ -528,48 +528,48 @@ calculations.
 - **Description**: It indicates which occupation and smearing method is used in the calculation.
   - fixed: use fixed occupations.
   - gauss or gaussian: use gaussian smearing method.
-  - mp: use methfessel-paxton smearing method. The method recommends for metals.
+  - mp: use methfessel-paxton smearing method. The method is recommended for metals.
   - fd: Fermi-Dirac smearing method: $f=1/\{1+\exp[(E-\mu)/kT]\}$ and smearing_sigma below is the temperature $T$ (in Ry).
 - **Default**: fixed
 
 #### smearing_sigma
 
 - **Type**: Real
-- **Description**: energy range for smearing, the unit is Rydberg.
+- **Description**: Relevant when `smearing_method` is **NOT** `fixed`.Specified the energy range for smearing, the unit is Rydberg.
 - **Default**: 0.001
 
 #### smearing_sigma_temp
 
 - **Type**: Real
-- **Description**: energy range for smearing, and is same as smearing_sigma, but the unit is K. smearing_sigma = 1/2 * kB * smearing_sigma_temp.
+- **Description**: Do not use this along with smearing_sigma. Energy range for smearing, but with Kelvin as unit. smearing_sigma = 1/2 * kB * smearing_sigma_temp.
 
 #### mixing_type
 
 - **Type**: String
-- **Description**: Charge mixing methods.
-  - plain: Just simple mixing.
-  - kerker: Use kerker method, which is the mixing method in G space.
-  - pulay: Standard Pulay method.
-  - pulay-kerker:
-  - broyden: Broyden method.
+- **Description**: Selecting one of the following mixing methods.
+  - plain: Simple linear mixing: $\rho^{in}_{i+1} = \rho_i^{in} + \beta[\rho_i^{out} - \rho_i^{in}]$.
+  - kerker: Plain mixing with Kerker pre-conditioning, where short wavevectors are suppressed to prevent charge sloshing in metallic systems : $\rho^{in}_{i+1}(G) = \rho_i^{in}(G) + \beta\frac{G^2}{G^2+\lambda^2}[\rho_i^{out}(G) - \rho_i^{in}(G)]$
+  - pulay: Standard Pulay method, also known as direct inversion in the iterative subspace (DIIS). $\rho^{out}$ is obtained as linear combination of previous steps. The expansion coefficients are obtained by inverting a residual matrix.
+  - pulay-kerker : Pulay method with Kerker pre-conditioning to prevent charge sloshing.
+  - broyden: [simplified Broyden](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.38.12807) mixing method.
 - **Default**: pulay
 
 #### mixing_beta
 
 - **Type**: Real
-- **Description**: mixing parameter: 0 means no new charge
+- **Description**: This parameter controls the fraction of $\rho_i^{out}$ in $\rho^{in}_{i+1}$. If set to 0, the electron density is never updated.
 - **Default**: 0.7
 
 #### mixing_ndim
 
 - **Type**: Integer
-- **Description**: It indicates the mixing dimensions in Pulay, Pulay method use the density from previous mixing_ndim steps and do a charge mixing based on these density.
+- **Description**: Relevant when `mixing_type` is set to `pulay` or `pulay-kerker`. It indicates the mixing dimensions in Pulay, Pulay method use the density from previous mixing_ndim steps and do a charge mixing based on these density.
 - **Default**: 8
 
 #### mixing_gg0
 
 - **Type**: Real
-- **Description**: used in pulay-kerker mixing method
+- **Description**: Relevant when `mixing_type` is set to `kerker` or `pulay-kerker`. A larger `mixing_gg0` means increased suppressiong of the short wavevectors.
 - **Default**: 1.5
 
 #### gamma_only

examples/charge_mixing/pw_Al/INPUT_1

@@ -0,0 +1,25 @@
+INPUT_PARAMETERS
+#Parameters (1.General)
+suffix			autotest
+calculation     scf
+ntype			1
+nbands			8
+symmetry		1
+pseudo_dir	../../../tests/PP_ORB
+
+#Parameters (2.Iteration)
+ecutwfc			30
+scf_thr				1e-9
+scf_nmax			100
+
+#Parameters (3.Basis)
+basis_type		pw
+latname fcc
+
+#Parameters (4.Smearing)
+smearing_method		gauss
+smearing_sigma			0.002
+
+#Parameters (5.Mixing)
+mixing_type		pulay
+mixing_beta		0.7

examples/charge_mixing/pw_Al/INPUT_2

@@ -0,0 +1,25 @@
+INPUT_PARAMETERS
+#Parameters (1.General)
+suffix			autotest
+calculation     scf
+ntype			1
+nbands			8
+symmetry		1
+pseudo_dir	../../../tests/PP_ORB
+
+#Parameters (2.Iteration)
+ecutwfc			30
+scf_thr				1e-9
+scf_nmax			100
+
+#Parameters (3.Basis)
+basis_type		pw
+latname fcc
+
+#Parameters (4.Smearing)
+smearing_method		gauss
+smearing_sigma			0.002
+
+#Parameters (5.Mixing)
+mixing_type		plain
+mixing_beta		0.7

examples/charge_mixing/pw_Al/INPUT_3

@@ -0,0 +1,25 @@
+INPUT_PARAMETERS
+#Parameters (1.General)
+suffix			autotest
+calculation     scf
+ntype			1
+nbands			8
+symmetry		1
+pseudo_dir	../../../tests/PP_ORB
+
+#Parameters (2.Iteration)
+ecutwfc			30
+scf_thr				1e-9
+scf_nmax			100
+
+#Parameters (3.Basis)
+basis_type		pw
+latname fcc
+
+#Parameters (4.Smearing)
+smearing_method		gauss
+smearing_sigma			0.002
+
+#Parameters (5.Mixing)
+mixing_type		pulay
+mixing_beta		0.2

examples/charge_mixing/pw_Al/INPUT_4

@@ -0,0 +1,25 @@
+INPUT_PARAMETERS
+#Parameters (1.General)
+suffix			autotest
+calculation     scf
+ntype			1
+nbands			8
+symmetry		1
+pseudo_dir	../../../tests/PP_ORB
+
+#Parameters (2.Iteration)
+ecutwfc			30
+scf_thr				1e-9
+scf_nmax			100
+
+#Parameters (3.Basis)
+basis_type		pw
+latname fcc
+
+#Parameters (4.Smearing)
+smearing_method		gauss
+smearing_sigma			0.002
+
+#Parameters (5.Mixing)
+mixing_type		plain
+mixing_beta		0.2

examples/charge_mixing/pw_Al/KPT

@@ -0,0 +1,4 @@
+K_POINTS
+0
+Gamma
+2 2 2 0 0 0

examples/charge_mixing/pw_Al/README

@@ -0,0 +1,5 @@
+Showcasing different charge mixing methods
+- INPUT_1 : pulay mixing with beta=0.7, takes 5 steps to converge
+- INPUT_2 : plain mixing with beta=0.7, takes 8 steps to converge
+- INPUT_3 : pulay mixing with beta=0.2, takes 6 steps to converge
+- INPUT_4 : plain mixing with beta=0.2, takes 37 steps to converge

examples/charge_mixing/pw_Al/STRU

@@ -0,0 +1,14 @@
+ATOMIC_SPECIES
+Al 26.98 Al.pz-vbc.UPF upf201
+
+LATTICE_CONSTANT
+7.50
+
+
+ATOMIC_POSITIONS
+Direct
+
+Al
+0.0
+1
+0.00 0.00 0.00 1 1 1

examples/charge_mixing/pw_Al/result.ref

@@ -0,0 +1,3 @@
+etotref -57.66876692615671
+etotperatomref -57.6687669262
+totaltimeref 

examples/smearing/lcao_fe/INPUT_1

@@ -0,0 +1,22 @@
+INPUT_PARAMETERS
+suffix         autotest
+ntype          2
+
+calculation    scf
+ecutwfc        20
+scf_thr            1.0e-8
+scf_nmax          50
+out_chg     0
+
+smearing_method       gaussian
+smearing_sigma   0.02
+
+mixing_type    pulay
+mixing_beta    0.4
+
+ks_solver     genelpa
+basis_type    lcao
+gamma_only    1
+nspin         2
+pseudo_dir	../../../tests/PP_ORB
+orbital_dir	../../../tests/PP_ORB

examples/smearing/lcao_fe/INPUT_2

@@ -0,0 +1,21 @@
+INPUT_PARAMETERS
+suffix         autotest
+ntype          2
+
+calculation    scf
+ecutwfc        20
+scf_thr            1.0e-8
+scf_nmax          50
+out_chg     0
+
+smearing_method       fixed
+
+mixing_type    pulay
+mixing_beta    0.4
+
+ks_solver     genelpa
+basis_type    lcao
+gamma_only    1
+nspin         2
+pseudo_dir	../../../tests/PP_ORB
+orbital_dir	../../../tests/PP_ORB

examples/smearing/lcao_fe/KPT

@@ -0,0 +1,4 @@
+K_POINTS
+0
+Gamma
+1 1 1 0 0 0

examples/smearing/lcao_fe/README

@@ -0,0 +1,3 @@
+Example showing the importance of thermal smearing.
+- INPUT_1 : Gaussian smearing with smearing sigma = 0.02; takes 21 steps to converged
+- INPUT_2 : Fixed occupation (no smearing), not converging even at 50 steps

examples/smearing/lcao_fe/STRU

@@ -0,0 +1,29 @@
+ATOMIC_SPECIES
+Fe1 1.000 Fe_ONCV_PBE-1.0.upf
+Fe2 1.000 Fe_ONCV_PBE-1.0.upf
+
+NUMERICAL_ORBITAL
+Fe_gga_9au_100Ry_4s2p2d1f.orb
+Fe_gga_9au_100Ry_4s2p2d1f.orb
+
+LATTICE_CONSTANT
+15
+
+LATTICE_VECTORS
+ 1.00    0.50     0.50
+ 0.50    1.00     0.50
+ 0.50    0.50     1.00
+ATOMIC_POSITIONS
+Direct
+
+Fe1
+1.0
+1
+0.00            0.00            0.00            1        1       1
+
+Fe2
+-1.0
+1
+0.50            0.50            0.50            1        1       1
+
+

examples/smearing/lcao_fe/result.ref

@@ -0,0 +1,3 @@
+etotref -6372.520190290697
+etotperatomref -3186.2600951453
+totaltimeref 10.865