diff --git a/docs/advanced/elec_properties/density_matrix.md b/docs/advanced/elec_properties/density_matrix.md index 15b7ce9f44..5d6b8ab2e1 100644 --- a/docs/advanced/elec_properties/density_matrix.md +++ b/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,7 +47,9 @@ 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) @@ -45,8 +57,13 @@ ABACUS can also output the real-space density matrix DM(R) in CSR (Compressed Sp ``` 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`. diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index e61c1399d8..cca2483202 100644 --- a/docs/advanced/input_files/input-main.md +++ b/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 diff --git a/docs/parameters.yaml b/docs/parameters.yaml index ecfaa8906c..fc9cf99692 100644 --- a/docs/parameters.yaml +++ b/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 diff --git a/source/source_io/module_parameter/read_input_item_output.cpp b/source/source_io/module_parameter/read_input_item_output.cpp index 670540d0fa..e52ebfba34 100644 --- a/source/source_io/module_parameter/read_input_item_output.cpp +++ b/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";