From e8d1a09e23f7c19b4db76090df943e6958924658 Mon Sep 17 00:00:00 2001 From: sunliang98 <1700011430@pku.edu.cn> Date: Fri, 24 Apr 2026 16:12:58 +0800 Subject: [PATCH 1/5] Doc: Enhance the doc of scf_thr and scf_ene_thr --- docs/advanced/input_files/input-main.md | 4 ++-- docs/parameters.yaml | 4 ++-- .../source_io/module_parameter/read_input_item_elec_stru.cpp | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index 3d59ceb5e52..c14e59eb834 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -1361,14 +1361,14 @@ ### scf_thr - **Type**: Real -- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. +- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, SCF is considered converged only when both the charge-density criterion (`scf_thr`) and the total-energy criterion (`scf_ene_thr`) are satisfied. For local-orbital calculations, 1e-6 is usually accurate enough. - **Default**: 1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis). - **Unit**: Ry if scf_thr_type=1, dimensionless if scf_thr_type=2 ### scf_ene_thr - **Type**: Real -- **Description**: It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. +- **Description**: It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the electron densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). - **Default**: -1.0. If the user does not set this parameter, it will not take effect. - **Unit**: eV diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 8059ea953b6..02e840f5f00 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -823,7 +823,7 @@ parameters: category: Electronic structure type: Real description: | - It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough. + It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, SCF is considered converged only when both the charge-density criterion (`scf_thr`) and the total-energy criterion (`scf_ene_thr`) are satisfied. For local-orbital calculations, 1e-6 is usually accurate enough. default_value: "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)." unit: "Ry if scf_thr_type=1, dimensionless if scf_thr_type=2" availability: "" @@ -831,7 +831,7 @@ parameters: category: Electronic structure type: Real description: | - It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations. + It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the electron densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). default_value: "-1.0. If the user does not set this parameter, it will not take effect." unit: eV availability: "" diff --git a/source/source_io/module_parameter/read_input_item_elec_stru.cpp b/source/source_io/module_parameter/read_input_item_elec_stru.cpp index 0fe7ad35aa8..1a86273ca44 100644 --- a/source/source_io/module_parameter/read_input_item_elec_stru.cpp +++ b/source/source_io/module_parameter/read_input_item_elec_stru.cpp @@ -831,7 +831,7 @@ Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure item.annotation = "charge density error"; item.category = "Electronic structure"; item.type = "Real"; - item.description = "It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. Usually for local orbitals, usually 1e-6 may be accurate enough."; + item.description = "It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If scf_ene_thr is set, SCF is considered converged only when both the charge-density criterion (scf_thr) and the total-energy criterion (scf_ene_thr) are satisfied. For local-orbital calculations, 1e-6 is usually accurate enough."; item.default_value = "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)."; item.unit = "Ry if scf_thr_type=1, dimensionless if scf_thr_type=2"; item.availability = ""; @@ -865,7 +865,7 @@ Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure item.annotation = "total energy error threshold"; item.category = "Electronic structure"; item.type = "Real"; - item.description = "It's the energy threshold for electronic iteration. It represents the total energy error between two sequential densities from electronic iterations."; + item.description = "It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the electron densities before and after the Hpsi operation in one SCF step. It is not the same as the screen-output EDIFF, which is the energy difference before Hpsi and after charge mixing (i.e., across both Hpsi and charge-mixing operations)."; item.default_value = "-1.0. If the user does not set this parameter, it will not take effect."; item.unit = "eV"; item.availability = ""; From 1d8874e749ee528892f9e042c691a07b590864a6 Mon Sep 17 00:00:00 2001 From: sunliang98 <1700011430@pku.edu.cn> Date: Fri, 24 Apr 2026 16:16:55 +0800 Subject: [PATCH 2/5] Doc: Update the doc --- docs/advanced/input_files/input-main.md | 2 +- docs/parameters.yaml | 2 +- source/source_io/module_parameter/read_input_item_elec_stru.cpp | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index c14e59eb834..391b2325c34 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -1368,7 +1368,7 @@ ### scf_ene_thr - **Type**: Real -- **Description**: It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the electron densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). +- **Description**: It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the charge densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). - **Default**: -1.0. If the user does not set this parameter, it will not take effect. - **Unit**: eV diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 02e840f5f00..8fbce3a46b9 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -831,7 +831,7 @@ parameters: category: Electronic structure type: Real description: | - It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the electron densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). + It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the charge densities before and after the `Hpsi` operation in one SCF step. It is not the same as the screen-output `EDIFF`, which is the energy difference before `Hpsi` and after charge mixing (i.e., across both `Hpsi` and charge-mixing operations). default_value: "-1.0. If the user does not set this parameter, it will not take effect." unit: eV availability: "" diff --git a/source/source_io/module_parameter/read_input_item_elec_stru.cpp b/source/source_io/module_parameter/read_input_item_elec_stru.cpp index 1a86273ca44..38c20de85b9 100644 --- a/source/source_io/module_parameter/read_input_item_elec_stru.cpp +++ b/source/source_io/module_parameter/read_input_item_elec_stru.cpp @@ -865,7 +865,7 @@ Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure item.annotation = "total energy error threshold"; item.category = "Electronic structure"; item.type = "Real"; - item.description = "It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the electron densities before and after the Hpsi operation in one SCF step. It is not the same as the screen-output EDIFF, which is the energy difference before Hpsi and after charge mixing (i.e., across both Hpsi and charge-mixing operations)."; + item.description = "It's the energy threshold for electronic iteration. The compared quantity is the total-energy difference evaluated from the charge densities before and after the Hpsi operation in one SCF step. It is not the same as the screen-output EDIFF, which is the energy difference before Hpsi and after charge mixing (i.e., across both Hpsi and charge-mixing operations)."; item.default_value = "-1.0. If the user does not set this parameter, it will not take effect."; item.unit = "eV"; item.availability = ""; From 2b4d596c6e29f40a101eb1273b47f2cc3e57fc3c Mon Sep 17 00:00:00 2001 From: Liang Sun <50293369+sunliang98@users.noreply.github.com> Date: Fri, 24 Apr 2026 19:53:50 +0800 Subject: [PATCH 3/5] Update source/source_io/module_parameter/read_input_item_elec_stru.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- source/source_io/module_parameter/read_input_item_elec_stru.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/source_io/module_parameter/read_input_item_elec_stru.cpp b/source/source_io/module_parameter/read_input_item_elec_stru.cpp index 38c20de85b9..39f37febc54 100644 --- a/source/source_io/module_parameter/read_input_item_elec_stru.cpp +++ b/source/source_io/module_parameter/read_input_item_elec_stru.cpp @@ -831,7 +831,7 @@ Note: If gamma_only is set to 1, the KPT file will be overwritten. So make sure item.annotation = "charge density error"; item.category = "Electronic structure"; item.type = "Real"; - item.description = "It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If scf_ene_thr is set, SCF is considered converged only when both the charge-density criterion (scf_thr) and the total-energy criterion (scf_ene_thr) are satisfied. For local-orbital calculations, 1e-6 is usually accurate enough."; + item.description = "It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If scf_ene_thr is set, the total-energy criterion (scf_ene_thr) is additionally checked only after the first SCF iteration and only when the charge-density criterion (scf_thr) has already been satisfied. For local-orbital calculations, 1e-6 is usually accurate enough."; item.default_value = "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)."; item.unit = "Ry if scf_thr_type=1, dimensionless if scf_thr_type=2"; item.availability = ""; From de8a13786196a1e8d7203941cde0577d805d1d69 Mon Sep 17 00:00:00 2001 From: Liang Sun <50293369+sunliang98@users.noreply.github.com> Date: Fri, 24 Apr 2026 19:54:04 +0800 Subject: [PATCH 4/5] Update docs/parameters.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/parameters.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/parameters.yaml b/docs/parameters.yaml index 8fbce3a46b9..63ee83376c5 100644 --- a/docs/parameters.yaml +++ b/docs/parameters.yaml @@ -823,7 +823,7 @@ parameters: category: Electronic structure type: Real description: | - It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, SCF is considered converged only when both the charge-density criterion (`scf_thr`) and the total-energy criterion (`scf_ene_thr`) are satisfied. For local-orbital calculations, 1e-6 is usually accurate enough. + It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, the total-energy criterion (`scf_ene_thr`) is evaluated conditionally after the charge-density criterion (`scf_thr`) is satisfied, and not on the first iteration. For local-orbital calculations, 1e-6 is usually accurate enough. default_value: "1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis)." unit: "Ry if scf_thr_type=1, dimensionless if scf_thr_type=2" availability: "" From 1c62549af8eee0e16bbd157a84060ffc2f1203cf Mon Sep 17 00:00:00 2001 From: Liang Sun <50293369+sunliang98@users.noreply.github.com> Date: Fri, 24 Apr 2026 19:54:19 +0800 Subject: [PATCH 5/5] Update docs/advanced/input_files/input-main.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/advanced/input_files/input-main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/input_files/input-main.md b/docs/advanced/input_files/input-main.md index 391b2325c34..b5f458c21ea 100644 --- a/docs/advanced/input_files/input-main.md +++ b/docs/advanced/input_files/input-main.md @@ -1361,7 +1361,7 @@ ### scf_thr - **Type**: Real -- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, SCF is considered converged only when both the charge-density criterion (`scf_thr`) and the total-energy criterion (`scf_ene_thr`) are satisfied. For local-orbital calculations, 1e-6 is usually accurate enough. +- **Description**: It's the density threshold for electronic iteration. It represents the charge density error between two sequential densities from electronic iterations. This criterion is always enabled. If `scf_ene_thr` is set, its total-energy criterion is applied as an additional convergence check only after the charge-density criterion (`scf_thr`) has been satisfied, and only from the second SCF iteration onward (`iter > 1`). For local-orbital calculations, 1e-6 is usually accurate enough. - **Default**: 1.0e-9 (plane-wave basis), or 1.0e-7 (localized atomic orbital basis). - **Unit**: Ry if scf_thr_type=1, dimensionless if scf_thr_type=2