From 10098279f337f1870ce7bb79bc2fcb0bf3d4a6ed Mon Sep 17 00:00:00 2001 From: sunliang98 <1700011430@pku.edu.cn> Date: Tue, 14 Apr 2026 21:09:54 +0800 Subject: [PATCH 1/3] Update the doc of out_dmk --- .../elec_properties/density_matrix.md | 21 ++++++++++++++++--- docs/advanced/input_files/input-main.md | 5 ++++- docs/parameters.yaml | 4 +++- 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/advanced/elec_properties/density_matrix.md b/docs/advanced/elec_properties/density_matrix.md index 15b7ce9f44..9ef80741aa 100644 --- a/docs/advanced/elec_properties/density_matrix.md +++ b/docs/advanced/elec_properties/density_matrix.md @@ -1,10 +1,18 @@ # 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`): `dm_nao.csr` (`nspin=1/4`) or `dms1_nao.csr` and `dms2_nao.csr` (`nspin=2`) +- multi-k (`gamma_only = 0`): `dmk1_nao.csr`, `dmk2_nao.csr`, ... (`nspin=1/4`) or `dmk1s1_nao.csr`, `dmk1s2_nao.csr`, ... (`nspin=2`) + +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 +45,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 +55,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..8177e0c8ba 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -1810,7 +1810,10 @@ - nspin = 1 and 4: dmk1_nao.csr, dmk2_nao.csr, ...; - nspin = 2: dmk1s1_nao.csr... and dmk1s2_nao.csr... 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. + > 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..5b813699b5 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -2864,7 +2864,9 @@ parameters: * nspin = 1 and 4: dmk1_nao.csr, dmk2_nao.csr, ...; * nspin = 2: dmk1s1_nao.csr... and dmk1s2_nao.csr... 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. + [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 From fdede5ee68bdc514ec67fa6797e79c88fc01e5ea Mon Sep 17 00:00:00 2001 From: sunliang98 <1700011430@pku.edu.cn> Date: Tue, 14 Apr 2026 21:26:55 +0800 Subject: [PATCH 2/3] Doc: correct the filename of dm --- docs/advanced/elec_properties/density_matrix.md | 6 ++++-- docs/advanced/input_files/input-main.md | 12 +++++++----- docs/parameters.yaml | 11 ++++++----- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/advanced/elec_properties/density_matrix.md b/docs/advanced/elec_properties/density_matrix.md index 9ef80741aa..5d6b8ab2e1 100644 --- a/docs/advanced/elec_properties/density_matrix.md +++ b/docs/advanced/elec_properties/density_matrix.md @@ -7,8 +7,10 @@ out_dmk 1 After finishing the calculation, the density matrix is written into `OUT.${suffix}/`. For current develop versions: -- gamma-only (`gamma_only = 1`): `dm_nao.csr` (`nspin=1/4`) or `dms1_nao.csr` and `dms2_nao.csr` (`nspin=2`) -- multi-k (`gamma_only = 0`): `dmk1_nao.csr`, `dmk2_nao.csr`, ... (`nspin=1/4`) or `dmk1s1_nao.csr`, `dmk1s2_nao.csr`, ... (`nspin=2`) +- 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`. diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index 8177e0c8ba..cca2483202 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -1802,13 +1802,15 @@ - **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. + + Here, g{istep} denotes the geometry/step index in the output file name. > Note: Version difference (develop vs 3.10-LTS): > diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 5b813699b5..fc9cf99692 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -2856,13 +2856,14 @@ 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] Version difference (develop vs 3.10-LTS): * In develop, out_dmk supports both gamma-only and multi-k-point density-matrix output. From 0cde2d591412e8d4d84dc20ad84774853c8f7f39 Mon Sep 17 00:00:00 2001 From: sunliang98 <1700011430@pku.edu.cn> Date: Tue, 14 Apr 2026 22:23:33 +0800 Subject: [PATCH 3/3] Update read_input_item_output.cpp --- .../read_input_item_output.cpp | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) 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";