Merge branch 'develop' into fix-out-flag

.github/workflows/coverage.yml

@@ -25,7 +25,7 @@ jobs:
         env:
           OMP_NUM_THREADS: 1
         run: |
-          cmake --build build --target test ARGS="-V --timeout 21600"
+          cmake --build build --target test ARGS="-V --timeout 21600" || exit 0
       - name: Upload Coverage to Codecov
         uses: codecov/codecov-action@v4
         if: ${{ ! cancelled() }}

.gitmodules

@@ -1,11 +1,3 @@
-[submodule "deps/LibRI"]
-	path = deps/LibRI
-	url = https://github.com/abacusmodeling/LibRI.git
-	branch = master
-[submodule "deps/LibComm"]
-	path = deps/LibComm
-	url = https://github.com/abacusmodeling/LibComm.git
-	branch = master
 [submodule "deps/libpaw_interface"]
 	path = deps/libpaw_interface
 	url = https://github.com/wenfei-li/libpaw_interface

CMakeLists.txt

@@ -538,13 +538,10 @@ endif()
 if(ENABLE_LIBRI)
   set_if_higher(CMAKE_CXX_STANDARD 14)
   if(LIBRI_DIR)
-    include_directories(${LIBRI_DIR}/include)
-  elseif(GIT_SUBMODULE)
-    git_submodule_update()
-    include_directories(${CMAKE_CURRENT_SOURCE_DIR}/deps/LibRI/include)
   else()
-    message(FATAL_ERROR "Must provide LIBRI_DIR for RI related features.")
+    find_package(LibRI REQUIRED)
   endif()
+  include_directories(${LIBRI_DIR}/include)
   target_link_libraries(${ABACUS_BIN_NAME} ri module_exx_symmetry)
   add_compile_definitions(__EXX EXX_DM=3 EXX_H_COMM=2 TEST_EXX_LCAO=0
                           TEST_EXX_RADIAL=1)
@@ -555,13 +552,10 @@ if(ENABLE_LIBRI OR DEFINED LIBCOMM_DIR)
 endif()
 if(ENABLE_LIBCOMM)
   if(LIBCOMM_DIR)
-    include_directories(${LIBCOMM_DIR}/include)
-  elseif(GIT_SUBMODULE)
-    git_submodule_update()
-    include_directories(${CMAKE_CURRENT_SOURCE_DIR}/deps/LibComm/include)
   else()
-    message(FATAL_ERROR "Must provide LIBCOMM_DIR for RI related features.")
+    find_package(LibComm REQUIRED)
   endif()
+  include_directories(${LIBCOMM_DIR}/include)
 endif()
 
 if(ENABLE_PAW)

cmake/FindLibComm.cmake

@@ -0,0 +1,30 @@
+###############################################################################
+# - Find LibComm
+# Find the native LibComm files.
+#
+#  LIBCOMM_FOUND - True if LibComm is found.
+#  LIBCOMM_DIR - Where to find LibComm files.
+
+find_path(LIBCOMM_DIR
+    include/Comm/Comm_Tools.h
+    HINTS ${LIBCOMM_DIR}
+    HINTS ${LibComm_DIR}
+    HINTS ${libcomm_DIR}
+)
+
+if(NOT LIBCOMM_DIR)
+    include(FetchContent)
+    FetchContent_Declare(
+        LibComm
+        URL https://github.com/abacusmodeling/LibComm/archive/refs/tags/v0.1.1.tar.gz
+    )
+    FetchContent_Populate(LibComm)
+    set(LIBCOMM_DIR ${libcomm_SOURCE_DIR})
+endif()
+# Handle the QUIET and REQUIRED arguments and
+# set LIBCOMM_FOUND to TRUE if all variables are non-zero.
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(LibComm DEFAULT_MSG LIBCOMM_DIR)
+
+# Copy the results to the output variables and target.
+mark_as_advanced(LIBCOMM_DIR)

cmake/FindLibRI.cmake

@@ -0,0 +1,30 @@
+###############################################################################
+# - Find LibRI
+# Find the native LibRI files.
+#
+#  LIBRI_FOUND - True if LibRI is found.
+#  LIBRI_DIR - Where to find LibRI files.
+
+find_path(LIBRI_DIR
+    include/RI/version.h
+    HINTS ${LIBRI_DIR}
+    HINTS ${LibRI_DIR}
+    HINTS ${libri_DIR}
+)
+
+if(NOT LIBRI_DIR)
+    include(FetchContent)
+    FetchContent_Declare(
+        LibRI
+        URL https://github.com/abacusmodeling/LibRI/archive/refs/tags/v0.2.1.1.tar.gz
+    )
+    FetchContent_Populate(LibRI)
+    set(LIBRI_DIR ${libri_SOURCE_DIR})
+endif()
+# Handle the QUIET and REQUIRED arguments and
+# set LIBRI_FOUND to TRUE if all variables are non-zero.
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(LibRI DEFAULT_MSG LIBRI_DIR)
+
+# Copy the results to the output variables and target.
+mark_as_advanced(LIBRI_DIR)

docs/advanced/input_files/input-main.md

@@ -88,6 +88,9 @@
     - [scf\_thr](#scf_thr)
     - [scf\_ene\_thr](#scf_ene_thr)
     - [scf\_thr\_type](#scf_thr_type)
+    - [scf\_os\_stop](#scf_os_stop)
+    - [scf\_os\_thr](#scf_os_thr)
+    - [scf\_os\_ndim](#scf_os_ndim)
     - [chg\_extrap](#chg_extrap)
     - [lspinorb](#lspinorb)
     - [noncolin](#noncolin)
@@ -1173,7 +1176,7 @@ Note: In new angle mixing, you should set `mixing_beta_mag >> mixing_beta`. The
 
 - **Type**: Integer
 - **Description**: Print out energy for each band for every printe step
-- **Default**: 100
+- **Default**: `scf_nmax`
 
 ### scf_nmax
 
@@ -1205,6 +1208,29 @@ Note: In new angle mixing, you should set `mixing_beta_mag >> mixing_beta`. The
 
 - **Default**: 1 (plane-wave basis), or 2 (localized atomic orbital basis).
 
+### scf_os_stop
+
+- **Type**: bool
+- **Description**: For systems that are difficult to converge, the SCF process may exhibit oscillations in charge density, preventing further progress toward the specified convergence criteria and resulting in continuous oscillation until the maximum number of steps is reached; this greatly wastes computational resources. To address this issue, this function allows ABACUS to terminate the SCF process early upon detecting oscillations, thus reducing subsequent meaningless calculations. The detection of oscillations is based on the slope of the logarithm of historical drho values.. To this end, Least Squares Method is used to calculate the slope of the logarithmically taken drho for the previous `scf_os_ndim` iterations. If the calculated slope is larger than `scf_os_thr`, stop the SCF.
+
+  - **0**: The SCF will continue to run regardless of whether there is oscillation or not. 
+  - **1**: If the calculated slope is larger than `scf_os_thr`, stop the SCF.
+
+- **Default**: false
+
+### scf_os_thr
+
+- **Type**: double
+- **Description**: The slope threshold to determine if the SCF is stuck in a charge density oscillation. If the calculated slope is larger than `scf_os_thr`, stop the SCF.
+
+- **Default**: -0.01
+
+### scf_os_ndim
+
+- **Type**: int
+- **Description**: To determine the number of old iterations' `drho` used in slope calculations.
+- **Default**: `mixing_ndim`
+
 ### chg_extrap
 
 - **Type**: String

examples/bravais_lattice/fcc_SiO2/INPUT

@@ -3,8 +3,13 @@ INPUT_PARAMETERS
 pseudo_dir              ../../../tests/PP_ORB	
 calculation		scf
 #Parameters (Accuracy)
-ecutwfc			50
+ecutwfc			 60 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_thr         	1e-8
 scf_nmax		20
 basis_type		pw
 latname			fcc
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/bravais_lattice/hexagonal_MoS2/INPUT

@@ -3,9 +3,14 @@ INPUT_PARAMETERS
 pseudo_dir              ../../../tests/PP_ORB	
 calculation             scf
 #Parameters (Accuracy)
-ecutwfc			50
+ecutwfc			 60 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_thr         	1e-8
 scf_nmax		20
 smearing_sigma		0.002
 basis_type		pw
 latname			hexagonal
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/bravais_lattice/so_SnTe/INPUT

@@ -1,8 +1,13 @@
 INPUT_PARAMETERS
 pseudo_dir              	../../../tests/PP_ORB
 calculation             	scf
-ecutwfc                       	50
+ecutwfc                       	 60 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_thr                         1e-08
 scf_nmax                        100
 basis_type                    	pw
 latname				so
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/bsse/water/INPUT

@@ -3,12 +3,15 @@ INPUT_PARAMETERS
 pseudo_dir		../../../tests/PP_ORB
 orbital_dir		../../../tests/PP_ORB
 #Parameters (Accuracy)
-ecutwfc			50
+ecutwfc			 60 ### Please refer to orbital files[1] to set ecutwfc for LCAO basis.
 scf_nmax		100
 scf_thr                 1e-6
 basis_type		lcao
 
-gamma_only 1
+gamma_only 1 ### Abacus will generate KPT file when gamma_only=1.
 
 smearing_method gauss
 smearing_sigma 0.02
+
+
+### [1]The energy cutoff of a LCAO basis can be found in lines starting with "Energy Cutoff" of a .orb file.

examples/charge_density/lcao_nspin1_Si2/INPUT

@@ -8,8 +8,11 @@ nbands                          8
 basis_type                      lcao
 symmetry                        0       
 #Parameters (Accuracy)
-ecutwfc                         50
+ecutwfc                          60 ### Please refer to orbital files[1] to set ecutwfc for LCAO basis.
 scf_thr                         1.0e-7  // about iteration
 scf_nmax			100
 #Parameters (File)
 out_chg                         1
+
+
+### [1]The energy cutoff of a LCAO basis can be found in lines starting with "Energy Cutoff" of a .orb file.

examples/charge_density/pw_nspin1_Al/INPUT

@@ -5,10 +5,15 @@ calculation                     scf
 symmetry                        0
 #Parameters (Methos)
 basis_type                      pw
-ecutwfc                         50
+ecutwfc                          60 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_thr                         1.0e-8  // about iteration
 scf_nmax			100
 smearing_method         	gauss
-smearing_sigma          	0.01
+smearing_sigma          	0.015
 #Parameters (File)
 out_chg                         1
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/charge_density/pw_nspin2_Fe/INPUT

@@ -4,7 +4,7 @@ symmetry      1
 
 calculation   scf
 nspin         2
-ecutwfc       50
+ecutwfc        60 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_thr       1.0e-8
 scf_nmax      50
 out_chg       1
@@ -18,3 +18,8 @@ smearing_sigma       0.07
 mixing_type    broyden 
 mixing_beta    0.5
 
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/compensating_charge/Pt-slab/INPUT

@@ -4,11 +4,11 @@ dft_functional    pbe
 symmetry	  0
 cal_force	  1
 calculation       scf
-ecutwfc		  60
+ecutwfc		  60 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_nmax	  200
 scf_thr		  1.0e-7
 basis_type	  pw
-gamma_only        1
+gamma_only        1 ### Abacus will generate KPT file when gamma_only=1.
 smearing_method	  gauss
 smearing_sigma	  0.02
 mixing_type       broyden
@@ -22,3 +22,8 @@ block_up            0.75
 block_height        0.01
 block               1
 nelec               217
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/deepks/lcao_CsPbI3/INPUT

@@ -7,17 +7,17 @@ calculation             scf
 symmetry                0
 
 #Parameters (2.Iteration)
-ecutwfc                 100
+ecutwfc                 100 ### Please refer to orbital files[1] to set ecutwfc for LCAO basis.
 scf_thr                     1e-7
 scf_nmax                   50
 
 #Parameters (3.Basis)
 basis_type             lcao 
-kspacing               0.1
+kspacing               0.1 ### Abacus will generate KPT file when kspacing is used.
 
 #Parameters (4.Smearing)
 smearing_method                gaussian
-smearing_sigma                   0.0015
+smearing_sigma                   0.015
 
 #Parameters (5.Mixing)
 mixing_type             broyden
@@ -30,3 +30,6 @@ deepks_model	model.ptg
 #Parameters (7.SOC)
 lspinorb 1
 
+
+
+### [1]The energy cutoff of a LCAO basis can be found in lines starting with "Energy Cutoff" of a .orb file.

examples/deepks/lcao_H2O/INPUT

@@ -8,7 +8,7 @@ nbands                  16
 symmetry                0
 
 #Parameters (2.Iteration)
-ecutwfc                 50
+ecutwfc                  60 ### Please refer to orbital files[1] to set ecutwfc for LCAO basis.
 scf_thr                 1e-8
 scf_nmax                5
 
@@ -31,3 +31,6 @@ deepks_out_labels   1
 deepks_scf	        1
 deepks_model	    model.ptg
 deepks_bandgap      1
+
+
+### [1]The energy cutoff of a LCAO basis can be found in lines starting with "Energy Cutoff" of a .orb file.

examples/deepks/pw_H2O/INPUT

@@ -8,13 +8,13 @@ nbands                  6
 symmetry                0
 
 #Parameters (2.Iteration)
-ecutwfc                 100
+ecutwfc                 100 ###Energy cutoff needs to be tested to ensure your calculation is reliable.[1]
 scf_thr                     1e-8
 scf_nmax                   50
 
 #Parameters (3.Basis)
 basis_type              pw
-gamma_only              1
+gamma_only              1 ### Abacus will generate KPT file when gamma_only=1.
 
 #Parameters (4.Smearing)
 smearing_method                gaussian
@@ -29,3 +29,8 @@ bessel_descriptor_lmax			2
 bessel_descriptor_rcut 5
 bessel_descriptor_tolerence 1.0e-12
 
+
+
+### [1] Energy cutoff determines the quality of numerical quadratures in your calculations.
+###     So it is strongly recommended to test whether your result (such as converged SCF energies) is
+###     converged with respect to the energy cutoff.

examples/deepks/pw_H2O/KPT

@@ -2,3 +2,6 @@ K_POINTS
 0
 Gamma
 1 1 1 0 0 0
+### If you are running an energy calculation, please make sure your final energy is
+### converged with respect to the k-point settings, unless you set a loose k-point
+### mesh on purpose.

examples/density_matrix/lcao_nspin1_Si2/INPUT

@@ -8,9 +8,12 @@ nbands                          16
 basis_type                      lcao
 symmetry                        0       
 #Parameters (Accuracy)
-ecutwfc                         50
+ecutwfc                          60 ### Please refer to orbital files[1] to set ecutwfc for LCAO basis.
 scf_thr                         1.0e-7  // about iteration
 scf_nmax			100
 #Parameters (File)
 gamma_only			1
 out_dm                         1
+
+
+### [1]The energy cutoff of a LCAO basis can be found in lines starting with "Energy Cutoff" of a .orb file.