Doc: Update the doc of out_dmk

docs/advanced/elec_properties/density_matrix.md

@@ -1,10 +1,20 @@
 # Extracting Density Matrices
 
-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:
+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_dmk)" in INPUT file:
 ```
 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:
+After finishing the calculation, the density matrix is written into `OUT.${suffix}/`.
+
+For current develop versions:
+- gamma-only (`gamma_only = 1`): `dmg1_nao.txt` (`nspin=1/4`) or `dms1g1_nao.txt` and `dms2g1_nao.txt` (`nspin=2`)
+- multi-k (`gamma_only = 0`): `dmk1g1_nao.txt`, `dmk2g1_nao.txt`, ... (`nspin=1/4`) or `dmk1s1g1_nao.txt`, `dmk1s2g1_nao.txt`, ... (`nspin=2`)
+
+Here `g{istep}` denotes the geometry/step index in the output filename.
+
+For 3.10-LTS, the corresponding keyword is `out_dm`, and file names follow the legacy style such as `SPIN1_DM` and `SPIN2_DM`.
+
+The file content looks like:
 ```
 test
  5.39761
@@ -37,16 +47,23 @@ 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: Version difference summary:
+    - develop: `out_dmk` supports both gamma-only and multi-k-point output.
+    - 3.10-LTS: use `out_dm`.
 
 ## Real-space Density Matrix (CSR format)
 
 ABACUS can also output the real-space density matrix DM(R) in CSR (Compressed Sparse Row) format by setting:
 ```
 out_dmr    1
 ```
+This feature is only valid for multi-k calculations (`gamma_only = 0`).
+
 After the calculation, the density matrix files are written to `OUT.${suffix}/`:
+- develop naming pattern: `dmr{s}{spin index}{g}{geometry index}{_nao}.csr`
 - `nspin=1`: `dmrs1_nao.csr`
 - `nspin=2` (spin-polarized): `dmrs1_nao.csr` (spin-up) and `dmrs2_nao.csr` (spin-down)
 
+For 3.10-LTS, the corresponding keyword is `out_dm1`, and the file names are `data-DMR-sparse_SPIN0.csr` and `data-DMR-sparse_SPIN1.csr`, etc.
+
 These files can be used to restart calculations by setting `init_chg dm` in the INPUT file together with `read_file_dir` pointing to the directory containing the CSR files. This is supported for both `nspin=1` and `nspin=2`.

docs/advanced/input_files/input-main.md

@@ -1802,15 +1802,20 @@
 
 - **Type**: Boolean \[Integer\](optional)
 - **Availability**: *Numerical atomic orbital basis*
-- **Description**: Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. The files are named as:
+- **Description**: Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name:
   - For gamma only case:
-   - nspin = 1 and 4: dm_nao.csr;
-   - nspin = 2: dms1_nao.csr and dms2_nao.csr for the two spin channels.
+   - nspin = 1 and 4: dmg1_nao.txt;
+   - nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels.
   - For multi-k points case:
-   - nspin = 1 and 4: dmk1_nao.csr, dmk2_nao.csr, ...;
-   - nspin = 2: dmk1s1_nao.csr... and dmk1s2_nao.csr... for the two spin channels.
+   - nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...;
+   - nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels.
 
-  > Note: In the 3.10-LTS version, the parameter is named out_dm and the file names are SPIN1_DM and SPIN2_DM, etc.
+  Here, g{istep} denotes the geometry/step index in the output file name.
+
+  > Note: Version difference (develop vs 3.10-LTS):
+  >
+  > - In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output.
+  > - In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc.
 - **Default**: False
 
 ### out_dmr

docs/parameters.yaml

@@ -2856,15 +2856,18 @@ parameters:
     category: Output information
     type: "Boolean \\[Integer\\](optional)"
     description: |
-      Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. The files are named as:
+      Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name:
       * For gamma only case:
-       * nspin = 1 and 4: dm_nao.csr;
-       * nspin = 2: dms1_nao.csr and dms2_nao.csr for the two spin channels.
+       * nspin = 1 and 4: dmg1_nao.txt;
+       * nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels.
       * For multi-k points case:
-       * nspin = 1 and 4: dmk1_nao.csr, dmk2_nao.csr, ...;
-       * nspin = 2: dmk1s1_nao.csr... and dmk1s2_nao.csr... for the two spin channels.
+       * nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...;
+       * nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels.
+      Here, g{istep} denotes the geometry/step index in the output file name.
 
-      [NOTE] In the 3.10-LTS version, the parameter is named out_dm and the file names are SPIN1_DM and SPIN2_DM, etc.
+      [NOTE] Version difference (develop vs 3.10-LTS):
+      * In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output.
+      * In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc.
     default_value: "False"
     unit: ""
     availability: Numerical atomic orbital basis

source/source_io/module_parameter/read_input_item_output.cpp

@@ -156,15 +156,19 @@ In molecular dynamics calculations, the output frequency is controlled by out_fr
         item.annotation = ">0 output density matrix DM(k) for each k-point";
         item.category = "Output information";
         item.type = R"(Boolean \[Integer\](optional))";
-        item.description = R"(Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. The files are named as:
-* For gamma only case:
- * nspin = 1 and 4: dm_nao.csr;
- * nspin = 2: dms1_nao.csr and dms2_nao.csr for the two spin channels.
-* For multi-k points case:
- * nspin = 1 and 4: dmk1_nao.csr, dmk2_nao.csr, ...;
- * nspin = 2: dmk1s1_nao.csr... and dmk1s2_nao.csr... for the two spin channels.
+        item.description = R"(Whether to output the density matrix for each k-point into files in the folder OUT.${suffix}. For current develop versions, out_dmk writes *_nao.txt files and includes a g{istep} index in the file name:
+    * For gamma only case:
+     * nspin = 1 and 4: dmg1_nao.txt;
+     * nspin = 2: dms1g1_nao.txt and dms2g1_nao.txt for the two spin channels.
+    * For multi-k points case:
+     * nspin = 1 and 4: dmk1g1_nao.txt, dmk2g1_nao.txt, ...;
+     * nspin = 2: dmk1s1g1_nao.txt... and dmk1s2g1_nao.txt... for the two spin channels.
+
+    Here, g{istep} denotes the geometry/step index in the output file name.
 
-[NOTE] In the 3.10-LTS version, the parameter is named out_dm and the file names are SPIN1_DM and SPIN2_DM, etc.)";
+    [NOTE] Version difference (develop vs 3.10-LTS):
+    * In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output.
+    * In 3.10-LTS, the corresponding keyword is out_dm, and the output files are SPIN1_DM and SPIN2_DM, etc.)";
         item.default_value = "False";
         item.unit = "";
         item.availability = "Numerical atomic orbital basis";