Docs : accelerating SCF & writing HS matrices (#1319)

* 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

* docs : update part on structure optimization

* docs : update pp_orb

* docs : add examples

* docs : update typo

* docs : update interface list(only 1 layer)

* docs : update performance.md

* docs : update for outputting of hs matrices

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

docs/advanced/elec_properties/hs_matrix.md

@@ -1 +1,37 @@
-# Extracting Hamiltonian and Overlap Matrices
+# Extracting Hamiltonian and Overlap Matrices
+
+In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF calculation.
+
+For periodic systems, there are two ways to represent the matrices, the first is to write the entire square matrices for each k point, namely $H(k)$ and $S(k)$; the second is the R space representation, $H(R)$ and $S(R)$, where R is the lattice vector. The two representations are connected by Fourier transform: 
+
+- $H(k)=\sum_R H(R)e^{-ikR}$
+
+and
+
+- $S(k)=\sum_R S(R)e^{-ikR}$
+
+## out_mat_hs
+
+Users may set the keyword `out_mat_hs` to 1 for outputting the k-space matrices. It is available for both gamma_only and multi-k and calculations. Detailed description of the naming and formats of the output files are given [here](../input_files/input-main.md#outmaths).
+
+## out_mat_hs2
+
+The output of R-space matrices is controlled by the keyword `out_mat_hs2`. This functionality is not available for gamma_only calculations. To generate such matrices for gamma only calculations, users should turn off [gamma_only](../input_files/input-main.md#gammaonly), and explicitly specify that gamma point is the only k point in the KPT file.
+
+For a more detailed description of the naming and format of the matrices, refer to this [instruction](../input_files/input-main.md#outmaths2).
+
+
+## get_S
+We also offer the option of only calculating the overlap matrix without running SCF. For that purpose, in `INPUT` file we need to set the value keyword [calculation](../input_files/input-main.md#calculation) to be `get_S`.
+
+A file named `SR.csr` will be generated in the working directory, which contains the overlap matrix.
+
+## examples
+We provide [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/matrix_hs) of outputting the matrices. There are four examples:
+
+- out_hs2_multik : writing H(R) and S(R) for multi-k calculation
+- out_hs_gammaonly : writing H(k) and S(k) for gamma-only calculation
+- out_hs_multik : writing H(k) and S(k) for multi-k calculation
+- out_s_multik : running get_S for multi-k calculation
+
+Reference output files are provided in each directory.

docs/advanced/input_files/input-main.md

@@ -119,6 +119,7 @@ This part of variables are used to control general system parameters.
   - *test_memory* : checks memory required for the calculation. The number is not quite reliable, please use with care
   - *test_neighbour* : only performs neighbouring atom search
   - *gen_bessel* : generates projectors (a series of bessel functions) for DeePKS; see also keywords bessel_lmax, bessel_rcut and bessel_tol. A file named `jle.orb` will be generated which contains the projectors. An example is provided in examples/H2O-deepks-pw.
+  - *get_S* : only works for multi-k calculation with LCAO basis. Generates and writes the overlap matrix to a file names `SR.csr` in the working directory. The format of the file will be the same as that generated by [out_mat_hs2](#outmaths2).
 
 - **Default**: scf
 
@@ -128,7 +129,7 @@ This part of variables are used to control general system parameters.
 - **Description**: takes value 1, 0 and -1. 
   - if set to 1, symmetry analysis will be performed to determine the type of Bravais lattice and associated symmetry operations. (point groups only)
   - if set to 0, only time reversal symmetry would be considered in symmetry operations, which implied k point and -k point would be treated as one double weight k point.
-  - if set to -1, any symmetry will not be considered.
+  - if set to -1, no symmetry will be considered.
 - **Default**: 0
 
 #### kpar
@@ -522,7 +523,9 @@ calculations.
 
 - **Type**: Integer
 - **Description**: It is an important parameter **only to be used in localized orbitals set**.
-    It you set gamma_only = 1, ABACUS use gamma only, the algorithm is fast and you don't need to specify the k-points file. If you set gamma_only = 0, more than one k-point is used and the ABACUS is slower compared to gamma only algorithm.
+    If you set gamma_only = 1, ABACUS use gamma only, the algorithm is faster and you don't need to specify the k-points file. If you set gamma_only = 0, more than one k-point is used and the ABACUS is slower compared to gamma only algorithm.
+
+  > Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure to turn off gamma_only for multi-k calculations.
 - **Default**: 0
 
 #### printe

docs/advanced/input_files/kpt.md

@@ -8,6 +8,12 @@
 
 ABACUS uses periodic boundary conditions for both crystals and finite systems. For isolated systems, such as atoms, molecules, clusters, etc., one uses the so-called supercell model. Lattice vectors of the supercell are set in the `STRU` file. For the input k-point (`KPT`) file, the file should either contain the k-point coordinates and weights or the mesh size for creating the k-point gird. Both options are allowed in `ABACUS`.
 
+## Gamma-only Calculations
+
+In ABACUS, we offer th option of running gamma-only calculations for LCAO basis by setting [gamma_only](./input-main.md#gammaonly) to be 1. Due to details of implementation, gamma-only calculation will be slightly faster than running a non gamma-only calculation and explicitly setting gamma point to be the only the k-point, but the results should be consistent.
+
+> If gamma_only is set to 1, the KPT file will be overwritten. So make sure to turn off gamma_only for multi-k calculations.
+
 ## Generate k-mesh automatically
 
 To generate k-mesh automatically, it requires the input subdivisions of the Brillouin zone

docs/advanced/interface/index.rst

@@ -9,6 +9,5 @@ Interfaces to Other Softwares
    deepks
    dpgen
    deeph
-   ase
    phonopy
    Wannier90

docs/advanced/pp_orb.md

@@ -16,7 +16,7 @@ Users may also choose to generate their own atomic obitals. In ABACUS, the atomi
 
 For treating BSSE(Basis Set Superposition Error), we allow for the inclusion of "empty" or "ghost" atoms in the calculation. Namely, when expanding the Hamiltonian, basis sets on the atoms are used, while the ionic potentials on those atoms are not included when constructing the Hamiltonian.
 
-An empty atom is defined in the `STRU` file when an element name contains the "empty" suffix, such as "H_empty", "O_empty" and so on. Here we provide an [example]() of calculating the molecular formation energy of $H_2O$ with BSSE correction.
+An empty atom is defined in the `STRU` file when an element name contains the "empty" suffix, such as "H_empty", "O_empty" and so on. Here we provide an [example](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/bsse/water) of calculating the molecular formation energy of $H_2O$ with BSSE correction.
 
 In the example, we provide four STRU files:
 

docs/advanced/scf/performance.md

@@ -1,5 +1,31 @@
 # Accelerating the Calculation
 
+In ABACUS, we provide a few methods for accelerating the calculation. The parameters are usually set as default for calculations where there is not extreme concern for efficiency, as some of them may produce numerical issues under certain circumstances. In short, methods in this section should be used with care. It is better to calibrate the results against the default setting.
+
 ## K-point Parallelization
 
-## Accelerating Grid Integration
+In ABACUS, we offer k-point parallelization for calculations with PW basis, which should increase the efficiency when a large k-point mesh is used.
+
+To use k-point parallelization, users may set keyword [kpar](../input_files/input-main.md#kpar) to be larger than 1.
+
+> Note: It has been observed that k-point parallelization cannot work in conjunction with Davidson diagonalization.
+
+## K-point Symmetry
+
+Inclusion of k-point symmetry helps increasing the efficiency of calculations by reducing the effective number of k-points used. To turn on k-point symmetry, users may set keyword [symmetry](../input_files/input-main.md#symmetry) to be 1.
+
+> Note: In ABACUS we only support point-group symmetry but not space-group symmetry.
+
+## Accelerating Grid Integration
+
+For LCAO calculation, the matrix elements of the local potential is evaluated using grid integration. In grid integration, we group real-space FFT grid points into boxes of dimension bx * by * bz, and then proceed with the boxes as the basis unit of calculation.
+
+Setting [bx, by, bz](../input_files/input-main.md#bx-by-bz) to be values other than default might help with the efficiency of grid integration.
+
+> Note: the choice of bx, by, bz should be integer factors of the dimension of the real space FFT grid in each direction.
+
+## Low Dimension Materials
+
+In grid integration, we chose to parallelize the grid points along the z direction. Therefore, when using LCAO calculation for low dimension materials, it is recommended to put the material more evenly in z direction to avoid imbalanced workload on different MPI threads.
+
+Namely, when calculating 2D materials, it is better to put the material in xz or yz direction; while for 1D materials, it is better to align the material with the z direction.

examples/matrix_hs/out_hs2_multik/INPUT

@@ -0,0 +1,29 @@
+INPUT_PARAMETERS
+#Parameters (1.General)
+suffix			autotest
+calculation     scf
+ntype			1
+nbands			6
+symmetry		0
+pseudo_dir	../../../tests/PP_ORB
+orbital_dir	../../../tests/PP_ORB
+gamma_only      0
+
+#Parameters (2.Iteration)
+ecutwfc			20
+scf_thr				1e-8
+scf_nmax			1
+
+#Parameters (3.Basis)
+basis_type		lcao
+
+#Parameters (4.Smearing)
+smearing_method		gauss
+smearing_sigma			0.002
+
+#Parameters (5.Mixing)
+mixing_type		pulay
+mixing_beta		0.7
+
+out_mat_hs2  1
+ks_solver       genelpa

examples/matrix_hs/out_hs2_multik/KPT

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

examples/matrix_hs/out_hs2_multik/STRU

@@ -0,0 +1,22 @@
+ATOMIC_SPECIES
+Si 14 Si_ONCV_PBE-1.0.upf upf201
+
+NUMERICAL_ORBITAL
+Si_gga_8au_60Ry_2s2p1d.orb
+
+LATTICE_CONSTANT
+10.2  // add lattice constant
+
+LATTICE_VECTORS
+0.5 0.5 0.0
+0.5 0.0 0.5
+0.0 0.5 0.5
+
+ATOMIC_POSITIONS
+Direct 
+
+Si	// Element type	
+0.0	// magnetism
+2	
+0.00 0.00 0.00 1 1 1
+0.25 0.25 0.25 1 1 1