Update the 'get_s' command and related description. Update the 'DOS' output filenames. Move some functions in 'after_all_runners' to 'after_scf'. Change 'out_dm' to 'out_dmk' and change 'out_dm1' to 'out_dmr' (#6278)

* begin changing the output file names of out_mat_hs

* update output vxc an output tk

* Fix example 006_NO_GO_OH in 02_NAO_Gamma

* fix a bug

* fix 17_NO_KP_OH example in 03_NAO_multik

* partly update the 19_NO_KP_OH_nscf exxample and related codes

* partly update 20_NO_KP_OHS_S4

* fix the example 20_NO_KP_OHS_S4

* print out the information for H(R), S(R), H(k) and S(k)

* update 08_EXX examples

* update output filenames related to dH, dS, rR

* update documents

* add ctrl_output_lcao.h and ctrl_output_lcao.cpp files

* update ctrl_output_lcao function

* add more function in ctrl_output_lcao

* update ctrl_output_lcao

* update the output_mat_sparse function

* update p_hamilt class without the Device parameter

* add back functions in ctrl_output_lcao

* add back berry phase in ctrl_output_lcao

* add back wannier90

* add back rdmft

* update lcao_after_scf, this is before using ctrl_outut_lcao in lcao_after_scf

* update

* the functions turn normal, reconstruction finished

* merge

* fix bug related to deepks and exc

* update input-main.md

* fix exx codes

* update description for printing out H and S matrices

* change get_S to get_s

* update get_s document

* update the output of dos

* output dos when nspin = 2

* update the dos documents

* change out_dm to out_dmk and out_dm1 to out_dmr

* update out_dmk and out_dmr examples

* update the DOS name, update the output frequency of DOS for LCAO, not for PW yet

* update dos description

* add example relax_output, delete useless out_dm parameter in 11_PW_GPU tests

* update DOS related testing codes

* update 031 032 103 104

* update reference data for DOS

* fix a bug in example 05_NO_KP_DJ_OC2

* fix bug

* update SDFT DOS

* update dos ref

* update DOS examples

* update deepks examples

Author: mohanchen

docs/advanced/elec_properties/density_matrix.md

@@ -1,8 +1,8 @@
 # Extracting Density Matrices
 
-ABACUS can output the density matrix by adding the keyword "[out_dm](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-dm)" in INPUT file:
+ABACUS can output the density matrix by adding the keyword "[out_dmk](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-dm)" in INPUT file:
 ```
-out_dm             1
+out_dmk    1
 ```
 After finishing the calculation, the information of the density matrix is stroed in files `OUT.${suffix}/SPIN${spin}_DM`, which looks like:
 ```
@@ -37,4 +37,4 @@ The following line is dimension of the density matrix, and the rest lines are th
 
 The examples can be found in [examples/density_matrix](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/density_matrix)
 
-- Note: now this function is valid only for LCAO gamma only calcualtion.
+- Note: now this function is valid only for LCAO gamma only calcualtion.

docs/advanced/elec_properties/hs_matrix.md

@@ -1,8 +1,8 @@
 # Extracting Hamiltonian and Overlap Matrices
 
-In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF calculation.
+In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF calculations.
 
-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: 
+For periodic systems, there are two ways to construct the matrices, the first is to write the entire square matrices for each $k$ point in the Brillouin zone, namely $H(k)$ and $S(k)$; the second one is the real space representation, $H(R)$ and $S(R)$, where R is the Bravis lattice vector. The two representations are connected by Fourier transform:
 
 - $H(k)=\sum_R H(R)e^{-ikR}$
 
@@ -12,18 +12,9 @@ and
 
 ## out_mat_hs
 
-Users can set the keyword [out_mat_hs](../input_files/input-main.md#out_mat_hs) to true for outputting the upper triangular part of the Hamiltonian matrices and overlap matrices for each k point into files in the directory `OUT.${suffix}`. It is available for both gamma_only and multi-k calculations. 
+Users can set the keyword [out_mat_hs](../input_files/input-main.md#out_mat_hs) to true to print the upper triangular part of the Hamiltonian matrices and overlap matrices for each k point into files in the directory `OUT.${suffix}`. It is available for both gamma_only and multi-k calculations. 
 
-The files are named `data-$k-H` and `data-$k-S`, where `$k` is a composite index consisting of the k point index as well as the spin index. The corresponding sequence of the orbitals can be seen in [Basis Set](../pp_orb.md#basis-set).
-
-For nspin = 1 and nspin = 4 calculations, there will be only one spin component, so `$k` runs from 0 up to `$nkpoints-1`. For nspin = 2, `$k` runs from `2*$nkpoints-1`. In the latter case, the files are arranged into blocks of up and down spins. For example, if there are 3 k points, then we have the following correspondence:
-
-  - data-0-H : 1st k point, spin up
-  - data-1-H : 2nd k point, spin up
-  - data-2-H : 3rd k point, spin up
-  - data-3-H : 1st k point, spin down
-  - data-4-H : 2nd k point, spin down
-  - data-5-H : 3rd k point, spin down
+The $H(k)$ and $S(k)$ matrices are stored with numerical atomic orbitals as basis, and the corresponding sequence of the numerical atomic orbitals can be seen in [Basis Set](../pp_orb.md#basis-set).
 
 As for information on the k points, one may look for the `SETUP K-POINTS` section in the running log.
 
@@ -33,12 +24,10 @@ The rest of the file contains the upper triangular part of the specified matrice
 
 ## out_mat_hs2
 
-The output of R-space matrices is controlled by the keyword [out_mat_hs2](../input_files/input-main.md#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#gamma_only), and explicitly specify that gamma point is the only k point in the KPT file.
+The output of $H(R)$ and $S(R)$ matrices is controlled by the keyword [out_mat_hs2](../input_files/input-main.md#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#gamma_only), and explicitly specify that gamma point is the only k point in the KPT file.
 
 For single-point SCF calculations, if nspin = 1 or nspin = 4, two files `hrs1_nao.csr` and `sr_nao.csr` are generated, which contain the Hamiltonian matrix $H(R)$ and overlap matrix $S(R)$ respectively. For nspin = 2, three files `hrs1_nao.csr` and `hrs2_nao.csr` and `sr_nao.csr` are created, where the first two files correspodn to $H(R)$ for spin up and spin down, respectively.
 
-As for molecular dynamics calculations, the format is controlled by [out_interval](../input_files/input-main.md#out_interval) and [out_app_flag](../input_files/input-main.md#out_app_flag) in the same manner as the position matrix as detailed in [out_mat_r](../input_files/input-main.md#out_mat_r).
-
 Each file or each section of the appended file starts with three lines, the first gives the current ion/md step, the second gives the dimension of the matrix, and the last indicates how many different `R` are in the file.
 
 The rest of the files are arranged in blocks. Each block starts with a line giving the lattice vector `R` and the number of nonzero matrix elements, such as:
@@ -56,10 +45,12 @@ The CSR format stores a sparse m × n matrix M in row form using three (one-dime
   - The arrays V and COL_INDEX are of length NNZ, and contain the non-zero values and the column indices of those values respectively.
   - The array ROW_INDEX is of length m + 1 and encodes the index in V and COL_INDEX where the given row starts. This is equivalent to ROW_INDEX[j] encoding the total number of nonzeros above row j. The last element is NNZ , i.e., the fictitious index in V immediately after the last valid index NNZ - 1.
 
-## 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`.
+For calculations involving ionic movements, the output frequency of the matrix is controlled by [out_interval](../input_files/input-main.md#out_interval) and [out_app_flag](../input_files/input-main.md#out_app_flag). 
+
+## 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.
+A file named `sr_nao.csr` will be generated in the working directory, which contains the overlap matrix.
 
 > When `nspin` is set to 1 or 2, the dimension of the overlap matrix is nlocal $\times$ nlocal, where nlocal is the total number of numerical atomic orbitals. 
 These numerical atomic orbitals are ordered from outer to inner loop as atom, angular quantum number $l$, zeta (multiple radial orbitals corresponding to each $l$), and magnetic quantum number $m$. 
@@ -69,9 +60,9 @@ When `nspin` is set to 4, the dimension of the overlap matrix is (2 $\times$ nlo
 ## 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
+- 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_hs2_multik: writing H(R) and S(R) for multi-k calculation
+- out_s_multik: running calculation=get_s to obtain overlap matrix for multi-k calculation
 
 Reference output files are provided in each directory.

docs/advanced/elec_properties/position_matrix.md

@@ -20,5 +20,5 @@ Each block here contains the matrix for the corresponding cell. There are three
 
 In molecular dynamics (MD) calculations, if [out_app_flag](../input_files/input-main.md#out_app_flag) is set to true, then `data-rR-tr` is written in an append manner. Otherwise, output files will be put in a separate directory, `matrix`, and named as `$x`_data-rR-tr, where `$x` is the number of MD step. In addition, the output frequency is controlled by [out_interval](../input_files/input-main.md#out_interval). For example, if we are running a 10-step MD with out_interval = 3, then `$x` will be 0, 3, 6, and 9.
 
-## get_S
-We also offer the option of only calculating the position matrix without running SCF. For that purpose, in `INPUT` file we need to set the keyword [calculation](../input_files/input-main.md#calculation) to `get_S`, and [out_mat_r](../input_files/input-main.md#out_mat_r) to `true`.
+## get_s
+We also offer the option of only calculating the position matrix without running SCF. For that purpose, in `INPUT` file we need to set the keyword [calculation](../input_files/input-main.md#calculation) to `get_s`, and [out_mat_r](../input_files/input-main.md#out_mat_r) to `true`.

docs/advanced/input_files/input-main.md

@@ -133,8 +133,8 @@
     - [out\_freq\_elec](#out_freq_elec)
     - [out\_chg](#out_chg)
     - [out\_pot](#out_pot)
-    - [out\_dm](#out_dm)
-    - [out\_dm1](#out_dm1)
+    - [out\_dm](#out_dmk)
+    - [out\_dm1](#out_dmr)
     - [out\_wfc\_pw](#out_wfc_pw)
     - [out\_wfc\_lcao](#out_wfc_lcao)
     - [out\_dos](#out_dos)
@@ -503,7 +503,7 @@ These variables are used to control general system parameters.
   - md: perform molecular dynamics simulations
   - get_pchg: obtain partial (band-decomposed) charge densities (for LCAO basis only). See `nbands_istate` and `out_pchg` for more information
   - get_wf: obtain wave functions (for LCAO basis only). See `nbands_istate`, `out_wfc_norm` and `out_wfc_re_im` for more information
-  - get_S: obtain the overlap matrix formed by localized orbitals (for LCAO basis with multiple k points). the file name is `SR.csr` with file format being the same as that generated by [out_mat_hs2](#out_mat_hs2)
+  - get_s: obtain the overlap matrix formed by localized orbitals (for LCAO basis with multiple k points). the file name is `SR.csr` with file format being the same as that generated by [out_mat_hs2](#out_mat_hs2). Note: in the 3.10-LTS version, the command was named `get_S`
   - gen_bessel: generates projectors, i.e., a series of Bessel functions, for the DeePKS method (for LCAO basis only); see also keywords `bessel_descriptor_lmax`, `bessel_descriptor_rcut` and `bessel_descriptor_tolerence`. A file named `jle.orb` will be generated which contains the projectors. An example is provided in examples/H2O-deepks-pw
   - test_memory: obtain a rough estimation of memory consuption for the calculation
   - test_neighbour: obtain information of neighboring atoms (for LCAO basis only), please specify a positive [search_radius](#search_radius) manually
@@ -532,7 +532,7 @@ These variables are used to control general system parameters.
   - 1: Symmetry analysis will be performed to determine the type of Bravais lattice and associated symmetry operations. (point groups, space groups, primitive cells, and irreducible k-points)
 - **Default**:
   - 0:
-    - if [calculation](#calculation)==md/nscf/get_pchg/get_wf/get_S or [gamma_only](#gamma_only)==True;
+    - if [calculation](#calculation)==md/nscf/get_pchg/get_wf/get_s or [gamma_only](#gamma_only)==True;
     - If ([dft_fuctional](#dft_functional)==hse/hf/pbe0/scan0/opt_orb or [rpa](#rpa)==True). 
     - If [efield_flag](#efield_flag)==1
   - 1: else
@@ -1649,7 +1649,7 @@ These variables are used to control the output of properties.
 - **Default**: 0
 - **Note**: In the 3.10-LTS version, the file names are SPIN1_POT.cube and SPIN1_POT_INI.cube, etc. 
 
-### out_dm
+### out_dmk
 
 - **Type**: Boolean
 - **Availability**: Numerical atomic orbital basis
@@ -1661,17 +1661,17 @@ These variables are used to control the output of properties.
     - nspin = 1: `dms1k1_nao.csr`, `dms1k2_nao.csr`, ...;
     - nspin = 2: `dms1k1_nao.csr`... and `dms2k1_nao.csr`... for the two spin channels. 
 - **Default**: False
-- **Note**: In the 3.10-LTS version, the file names are SPIN1_DM and SPIN2_DM, etc.
+- **Note**: In the 3.10-LTS version, the parameter is named `out_dm` and the file names are SPIN1_DM and SPIN2_DM, etc.
 
-### out_dm1
+### out_dmr
 
 - **Type**: Boolean
 - **Availability**: Numerical atomic orbital basis (multi-k points)
 - **Description**: Whether to output the density matrix with Bravias lattice vector R index into files in the folder `OUT.${suffix}`. The files are named as `dmr{s}{spin index}{g}{geometry index}{_nao} + {".csr"}`. Here, 's' refers to spin, where s1 means spin up channel while s2 means spin down channel, and the sparse matrix format 'csr' is mentioned in [out_mat_hs2](#out_mat_hs2). Finally, if [out_app_flag](#out_app_flag) is set to false, the file name contains the optinal 'g' index for each ionic step that may have different geometries, and if [out_app_flag](#out_app_flag) is set to true, the density matrix with respect to Bravias lattice vector R accumulates during ionic steps:
   - nspin = 1: `dmrs1_nao.csr`;
   - nspin = 2: `dmrs1_nao.csr` and `dmrs2_nao.csr` for the two spin channels.
 - **Default**: False
-- **Note**: In the 3.10-LTS version, the file names are data-DMR-sparse_SPIN0.csr and data-DMR-sparse_SPIN1.csr, etc.
+- **Note**: In the 3.10-LTS version, the parameter is named `out_dm1`, and the file names are data-DMR-sparse_SPIN0.csr and data-DMR-sparse_SPIN1.csr, etc.
 
 ### out_wfc_pw
 
@@ -1710,7 +1710,9 @@ These variables are used to control the output of properties.
 - **Type**: Integer
 - **Description**: Whether to output the density of states (DOS). For more information, refer to the [dos.md](../elec_properties/dos.md).
   - 0: no output
-  - 1: output the density of states (DOS)
+  - 1: output the density of states (DOS) 
+    - nspin=1 or 4: `doss1g{geom}_{basis}.txt`, where geom is the geometry index when cell changes or ions move while basis is either `pw` or `nao`.
+    - nspin=2: `doss1g{geom}_{basis}.txt` and `doss2g{geom}_{basis}.txt` for two spin channles.
   - 2: (LCAO) output the density of states (DOS) and the projected density of states (PDOS)
   - 3: output the Fermi surface file (fermi.bxsf) in BXSF format that can be visualized by XCrySDen 
 - **Default**: 0
@@ -1811,7 +1813,7 @@ These variables are used to control the output of properties.
 
 - **Type**: Boolean
 - **Availability**: Numerical atomic orbital basis (not gamma-only algorithm)
-- **Description**: Whether to print the matrix representation of the position matrix into a file named `rr.csr` in the directory `OUT.${suffix}`. If [calculation](#calculation) is set to `get_S`, the position matrix can be obtained without scf iterations. For more information, please refer to [position_matrix.md](../elec_properties/position_matrix.md#extracting-position-matrices).
+- **Description**: Whether to print the matrix representation of the position matrix into a file named `rr.csr` in the directory `OUT.${suffix}`. If [calculation](#calculation) is set to `get_s`, the position matrix can be obtained without scf iterations. For more information, please refer to [position_matrix.md](../elec_properties/position_matrix.md#extracting-position-matrices).
 - **Default**: False
 - **Unit**: Bohr
 - **Note**: In the 3.10-LTS version, the file name is data-rR-sparse.csr. 
@@ -1838,7 +1840,7 @@ These variables are used to control the output of properties.
 
 - **Type**: Boolean
 - **Availability**: Numerical atomic orbital basis (not gamma-only algorithm)
-- **Description**: Whether to print files containing the derivatives of the overlap matrix. The format will be the same as the overlap matrix $dH(R)$ as mentioned in [out_mat_dh](#out_mat_dh). The name of the files will be `dsrxs1.csr` and so on. Also controled by [out_interval](#out_interval) and [out_app_flag](#out_app_flag). This feature can be used with `calculation get_S`.
+- **Description**: Whether to print files containing the derivatives of the overlap matrix. The format will be the same as the overlap matrix $dH(R)$ as mentioned in [out_mat_dh](#out_mat_dh). The name of the files will be `dsrxs1.csr` and so on. Also controled by [out_interval](#out_interval) and [out_app_flag](#out_app_flag). This feature can be used with `calculation get_s`.
 - **Default**: False
 - **Unit**: Ry/Bohr
 - **Note**: In the 3.10-LTS version, the file name is data-dSRx-sparse_SPIN0.csr and so on.

examples/README

@@ -1,10 +1,8 @@
 /*******************************************************************************/
-/
-/ These are the examples of ABACUS program.
-/
+/ Examples of ABACUS
 /*******************************************************************************/
 
-These examples show how to use ABACUS to do some specify calculations and how to 
+These examples show how to use ABACUS to run some specify calculations and how to 
 use the interfaces between ABACUS and some extenal softwares.
 
 The examples interface_XXXX show the using of interface of ABACUS and XXXX

examples/band/lcao_Si2/run.sh

@@ -13,7 +13,7 @@ scf_thr                         1.0e-7  // about iteration
 scf_nmax			100
 #Parameters (File)
 gamma_only			1
-out_dm                         1
+out_dmk                         1
 
 
 ### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.