CMake: Deprecate ENABLE_LIBCOMM and rename options (#7620)

* CMake: Treat LibComm as a LibRI implementation dependency

* Drop unused ENABLE_DEEPKS and ENABLE_MLKEDF

* Update CMake option

* Update documentation

* Rename compile definition

* FindKML: if(DEFINED ENABLE_OPENMP AND ENABLE_OPENMP) -> if(ENABLE_OPENMP)

* Adopt to toolchain building script

* Adjust generate_build_info.sh

* Link ABACUS binary under build root

* Update README.md and RapidJSON CMake test in toolchain

Author: Growl1234

CMakeLists.txt

@@ -14,7 +14,7 @@ project(
   LANGUAGES CXX)
 
 option(ENABLE_MPI "Enable MPI" ON)
-option(USE_OPENMP "Enable OpenMP" ON)
+option(ENABLE_OPENMP "Enable OpenMP" ON)
 option(USE_CUDA "Enable CUDA" OFF)
 option(USE_CUDA_MPI "Enable CUDA-aware MPI" OFF)
 option(USE_CUDA_ON_DCU "Enable CUDA on DCU" OFF)
@@ -23,27 +23,23 @@ option(USE_DSP "Enable DSP" OFF)
 option(USE_KML "Enable Kunpeng Math Library" OFF)
 option(USE_SW "Enable SW Architecture" OFF)
 
-option(USE_ABACUS_LIBM "Build libmath from source to speed up" OFF)
+option(ENABLE_ABACUS_LIBM "Build libmath from source to speed up" OFF)
 option(ENABLE_LIBXC "Enable using the LibXC package" OFF)
 option(ENABLE_FLOAT_FFTW "Enable using single-precision FFTW library." OFF)
 
-# option(ENABLE_DEEPKS "Enable the DeePKS algorithm" OFF)
-# option(ENABLE_MLKEDF "Enable the Machine-Learning-based KEDF for OFDFT" OFF)
-
 option(ENABLE_MLALGO "Enable the machine learning algorithms" OFF)
 
 option(ENABLE_LCAO "Enable LCAO algorithm" ON)
-option(USE_ELPA "Enable ELPA for LCAO" ON)
+option(ENABLE_ELPA "Enable ELPA for LCAO" ON)
 option(ENABLE_LIBRI "Enable LibRI for hybrid functional" OFF)
 option(EXX_DEV "Enable LibRI developing features" OFF)
-option(ENABLE_LIBCOMM "Enable LibComm" OFF)
 option(ENABLE_PEXSI "Enable PEXSI for LCAO" OFF)
 option(ENABLE_DFTD4 "Enable DFT-D4 dispersion correction" OFF)
 
 option(BUILD_TESTING "Build unittests" OFF)
 option(DEBUG_INFO "Print message to debug" OFF)
 option(ENABLE_ASAN "Enable AddressSanitizer" OFF)
-option(INFO "Enable gathering math library information" OFF)
+option(MATH_INFO "Enable gathering math library information" OFF)
 option(ENABLE_COVERAGE "Enable coverage build" OFF)
 option(GIT_SUBMODULE "Check submodules during build" ON)
 
@@ -59,6 +55,43 @@ option(ENABLE_CNPY "Enable cnpy usage" OFF)
 option(ENABLE_CUSOLVERMP "Enable cusolvermp" OFF)
 option(ENABLE_NCCL_PARALLEL_DEVICE "Enable NCCL-backed collectives in parallel_device" OFF)
 
+# ==============================================================================
+# Deprecated options (TODO: Remove this section in the future release)
+# ==============================================================================
+function(abacus_rename_option old_name new_name)
+  get_property(_old_defined CACHE "${old_name}" PROPERTY TYPE SET)
+  if(NOT _old_defined)
+    return()
+  endif()
+  message(WARNING "${old_name} has been renamed to ${new_name}.")
+  get_property(_type CACHE "${new_name}" PROPERTY TYPE)
+  get_property(_help CACHE "${new_name}" PROPERTY HELPSTRING)
+  set("${new_name}" "${${old_name}}" CACHE "${_type}" "${_help}" FORCE)
+  unset("${old_name}" CACHE)
+endfunction()
+abacus_rename_option(USE_OPENMP ENABLE_OPENMP)
+abacus_rename_option(USE_ABACUS_LIBM ENABLE_ABACUS_LIBM)
+abacus_rename_option(USE_ELPA ENABLE_ELPA)
+abacus_rename_option(INFO MATH_INFO)
+
+if(DEFINED CACHE{ENABLE_LIBCOMM})
+  message(
+    WARNING
+      "Option ENABLE_LIBCOMM is deprecated and will be ignored in a future release. "
+      "LibComm is now treated as an implementation dependency of LibRI; "
+      "please use -DENABLE_LIBRI=ON instead."
+  )
+  if(ENABLE_LIBCOMM AND NOT ENABLE_LIBRI)
+    message(
+      FATAL_ERROR
+        "ENABLE_LIBCOMM was set, but LibComm is not a standalone ABACUS feature. "
+        "Please use -DENABLE_LIBRI=ON instead."
+    )
+  endif()
+  unset(ENABLE_LIBCOMM CACHE)
+endif()
+# ==============================================================================
+
 # CTest defines BUILD_TESTING when it is first included. Include it only after
 # ABACUS has declared its OFF-by-default option above.
 include(CTest)
@@ -139,7 +172,7 @@ endif()
 
 # Serial version of ABACUS will not use ELPA
 if(NOT ENABLE_MPI)
-  set(USE_ELPA OFF)
+  set(ENABLE_ELPA OFF)
   set(ENABLE_MLALGO OFF)
 endif()
 
@@ -203,7 +236,7 @@ endif()
 
 # Use DSP hardware
 if (USE_DSP)
-  set(USE_ELPA OFF)
+  set(ENABLE_ELPA OFF)
   set(ABACUS_BIN_NAME abacus_dsp)
 endif()
 
@@ -288,14 +321,14 @@ endif()
 if(CMAKE_CXX_COMPILER_ID MATCHES Intel)
   # stick to strict floating point model on Intel Compiler
   add_compile_options(-fp-model=strict)
-  set(USE_ABACUS_LIBM OFF) # Force turn off USE_ABACUS_LIBM on Intel Compiler
+  set(ENABLE_ABACUS_LIBM OFF) # Force turn off ENABLE_ABACUS_LIBM on Intel Compiler
   set(CMAKE_CXX_FLAGS
       "${CMAKE_CXX_FLAGS} -Wno-write-strings "
   )
 endif()
 
-if(USE_ABACUS_LIBM)
-  abacus_add_feature_definitions(USE_ABACUS_LIBM)
+if(ENABLE_ABACUS_LIBM)
+  abacus_add_feature_definitions(__ABACUS_LIBM)
 endif()
 
 if(ENABLE_NATIVE_OPTIMIZATION)
@@ -311,9 +344,8 @@ if(WIN32)
 endif()
 
 if(ENABLE_LCAO)
-  find_package(cereal CONFIG REQUIRED)
   abacus_add_feature_definitions(__LCAO)
-  if(USE_ELPA)
+  if(ENABLE_ELPA)
     find_package(ELPA REQUIRED)
     abacus_add_feature_definitions(__ELPA)
   endif()
@@ -364,7 +396,7 @@ endif()
 
 find_package(Threads REQUIRED)
 
-if(USE_OPENMP)
+if(ENABLE_OPENMP)
   find_package(OpenMP REQUIRED)
 endif()
 
@@ -484,7 +516,7 @@ if(USE_CUDA)
     if (CMAKE_BUILD_TYPE STREQUAL "Debug")
       set(CMAKE_CUDA_FLAGS_DEBUG "${CMAKE_CUDA_FLAGS_DEBUG} -g -G" CACHE STRING "CUDA flags for debug build" FORCE)
     endif()
-    if (USE_OPENMP AND OpenMP_CXX_FOUND)
+    if (ENABLE_OPENMP AND OpenMP_CXX_FOUND)
       set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -Xcompiler=${OpenMP_CXX_FLAGS}" CACHE STRING "CUDA flags" FORCE)
     endif()
     if (ENABLE_NCCL_PARALLEL_DEVICE)
@@ -654,33 +686,18 @@ function(git_submodule_update)
   endif()
 endfunction()
 
-if(DEFINED LIBRI_DIR)
-  set(ENABLE_LIBRI ON)
-endif()
 if(ENABLE_LIBRI)
   set_if_higher(CMAKE_CXX_STANDARD 14)
-  if(LIBRI_DIR)
-  else()
-    find_package(LibRI REQUIRED)
-  endif()
+  find_package(LibRI REQUIRED)
+  find_package(LibComm REQUIRED)
+  find_package(cereal REQUIRED CONFIG)
   abacus_add_feature_definitions(__EXX EXX_DM=3 EXX_H_COMM=2 TEST_EXX_LCAO=0
                                  TEST_EXX_RADIAL=1)
   if(EXX_DEV)
     abacus_add_feature_definitions(__EXX_DEV)
   endif()
 endif()
 
-if(ENABLE_LIBRI OR DEFINED LIBCOMM_DIR)
-  set(ENABLE_LIBCOMM ON)
-endif()
-if(ENABLE_LIBCOMM)
-  if(LIBCOMM_DIR)
-  else()
-    find_package(LibComm REQUIRED)
-  endif()
-endif()
-
-
 if(ENABLE_LIBXC)
   find_package(Libxc CONFIG REQUIRED)
   if(Libxc_VERSION VERSION_LESS "5.1.7")
@@ -712,7 +729,7 @@ endif()
 
 abacus_add_feature_definitions(__FFTW3 __SELINV METIS)
 
-if(INFO)
+if(MATH_INFO)
   message(STATUS "Will gather math lib info.")
   abacus_add_feature_definitions(GATHER_INFO)
   # modifications on blas_connector and lapack_connector

cmake/CollectBuildInfoVars.cmake

@@ -136,16 +136,16 @@ if(ENABLE_MPI)
 endif()
 
 # OpenMP Version
-if(USE_OPENMP AND OpenMP_CXX_VERSION)
+if(ENABLE_OPENMP AND OpenMP_CXX_VERSION)
     set(ABACUS_OPENMP_VERSION "yes (v${OpenMP_CXX_VERSION})")
-elseif(USE_OPENMP)
+elseif(ENABLE_OPENMP)
     set(ABACUS_OPENMP_VERSION "yes (version unknown)")
 else()
     set(ABACUS_OPENMP_VERSION "no")
 endif()
 
 # Core Math Libraries
-if(ENABLE_LCAO AND USE_ELPA)
+if(ENABLE_LCAO AND ENABLE_ELPA)
     set(ABACUS_ELPA_VERSION "yes (version unknown)")
     if(ELPA_VERSION)
     set(ABACUS_ELPA_VERSION "yes (v${ELPA_VERSION})")
@@ -208,30 +208,6 @@ else()
     set(ABACUS_FFTW_VERSION "no (using MKL or SW)")
 endif()
 
-# Cereal Version (Enhanced)
-if(ENABLE_LCAO)
-    set(ABACUS_CEREAL_VERSION "yes (version unknown)")
-    if(NOT CEREAL_INCLUDE_DIR)
-        find_path(CEREAL_INCLUDE_DIR cereal/version.hpp)
-    endif()
-    if(CEREAL_INCLUDE_DIR AND EXISTS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp")
-        file(STRINGS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp" CEREAL_MAJOR_LINE REGEX "^#define CEREAL_VERSION_MAJOR")
-        file(STRINGS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp" CEREAL_MINOR_LINE REGEX "^#define CEREAL_VERSION_MINOR")
-        file(STRINGS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp" CEREAL_PATCH_LINE REGEX "^#define CEREAL_VERSION_PATCH")
-        string(REGEX REPLACE "^#define CEREAL_VERSION_MAJOR +([0-9]+).*" "\\1" CEREAL_MAJOR "${CEREAL_MAJOR_LINE}")
-        string(REGEX REPLACE "^#define CEREAL_VERSION_MINOR +([0-9]+).*" "\\1" CEREAL_MINOR "${CEREAL_MINOR_LINE}")
-        string(REGEX REPLACE "^#define CEREAL_VERSION_PATCH +([0-9]+).*" "\\1" CEREAL_PATCH "${CEREAL_PATCH_LINE}")
-        if(CEREAL_MAJOR AND CEREAL_MINOR AND CEREAL_PATCH)
-            set(ABACUS_CEREAL_VERSION "yes (v${CEREAL_MAJOR}.${CEREAL_MINOR}.${CEREAL_PATCH})")
-        endif()
-    endif()
-    if(ABACUS_CEREAL_VERSION STREQUAL "yes (version unknown)" AND CEREAL_INCLUDE_DIR)
-        set(ABACUS_CEREAL_VERSION "yes (path: ${CEREAL_INCLUDE_DIR})")
-    endif()
-else()
-    set(ABACUS_CEREAL_VERSION "no")
-endif()
-
 # Accelerators
 if(USE_CUDA AND CUDAToolkit_VERSION)
     set(ABACUS_CUDA_VERSION "yes (v${CUDAToolkit_VERSION})")
@@ -292,12 +268,37 @@ else()
     set(ABACUS_LIBRI_VERSION "no")
 endif()
 
-if(ENABLE_LIBCOMM AND LIBCOMM_DIR)
-    set(ABACUS_LIBCOMM_VERSION "yes (path: ${LIBCOMM_DIR})")
-elseif(ENABLE_LIBCOMM)
-    set(ABACUS_LIBCOMM_VERSION "yes (version unknown)")
+# LibComm Version
+if(ENABLE_LIBRI AND LIBCOMM_DIR)
+  set(ABACUS_LIBCOMM_VERSION "yes (path: ${LIBCOMM_DIR})")
+elseif(ENABLE_LIBRI)
+  set(ABACUS_LIBCOMM_VERSION "yes (version unknown)")
 else()
-    set(ABACUS_LIBCOMM_VERSION "no")
+  set(ABACUS_LIBCOMM_VERSION "no")
+endif()
+
+# Cereal Version (Enhanced)
+if(ENABLE_LIBRI)
+    set(ABACUS_CEREAL_VERSION "yes (version unknown)")
+    if(NOT CEREAL_INCLUDE_DIR)
+        find_path(CEREAL_INCLUDE_DIR cereal/version.hpp)
+    endif()
+    if(CEREAL_INCLUDE_DIR AND EXISTS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp")
+        file(STRINGS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp" CEREAL_MAJOR_LINE REGEX "^#define CEREAL_VERSION_MAJOR")
+        file(STRINGS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp" CEREAL_MINOR_LINE REGEX "^#define CEREAL_VERSION_MINOR")
+        file(STRINGS "${CEREAL_INCLUDE_DIR}/cereal/version.hpp" CEREAL_PATCH_LINE REGEX "^#define CEREAL_VERSION_PATCH")
+        string(REGEX REPLACE "^#define CEREAL_VERSION_MAJOR +([0-9]+).*" "\\1" CEREAL_MAJOR "${CEREAL_MAJOR_LINE}")
+        string(REGEX REPLACE "^#define CEREAL_VERSION_MINOR +([0-9]+).*" "\\1" CEREAL_MINOR "${CEREAL_MINOR_LINE}")
+        string(REGEX REPLACE "^#define CEREAL_VERSION_PATCH +([0-9]+).*" "\\1" CEREAL_PATCH "${CEREAL_PATCH_LINE}")
+        if(CEREAL_MAJOR AND CEREAL_MINOR AND CEREAL_PATCH)
+            set(ABACUS_CEREAL_VERSION "yes (v${CEREAL_MAJOR}.${CEREAL_MINOR}.${CEREAL_PATCH})")
+        endif()
+    endif()
+    if(ABACUS_CEREAL_VERSION STREQUAL "yes (version unknown)" AND CEREAL_INCLUDE_DIR)
+        set(ABACUS_CEREAL_VERSION "yes (path: ${CEREAL_INCLUDE_DIR})")
+    endif()
+else()
+    set(ABACUS_CEREAL_VERSION "no")
 endif()
 
 # ML & AI Libraries
@@ -384,11 +385,11 @@ endif()
 # --- 5. Collect CMake Configuration Summary ---
 set(ABACUS_CMAKE_OPTIONS "Build Options:")
 list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_MPI=${ENABLE_MPI}")
-list(APPEND CMAKE_OPTIONS_LIST "  USE_OPENMP=${USE_OPENMP}")
+list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_OPENMP=${ENABLE_OPENMP}")
 list(APPEND CMAKE_OPTIONS_LIST "  USE_CUDA=${USE_CUDA}")
 list(APPEND CMAKE_OPTIONS_LIST "  USE_ROCM=${USE_ROCM}")
 list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_LCAO=${ENABLE_LCAO}")
-list(APPEND CMAKE_OPTIONS_LIST "  USE_ELPA=${USE_ELPA}")
+list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_ELPA=${ENABLE_ELPA}")
 list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_LIBXC=${ENABLE_LIBXC}")
 list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_MLALGO=${ENABLE_MLALGO}")
 list(APPEND CMAKE_OPTIONS_LIST "  ENABLE_ASAN=${ENABLE_ASAN}")

cmake/modules/FindELPA.cmake

@@ -30,7 +30,7 @@ if(ELPA_INCLUDE_DIRS MATCHES "^/usr/include/elpa/.*")
     unset(ELPA_INCLUDE_DIRS)
   endif()
 endif()
-if(USE_OPENMP)
+if(ENABLE_OPENMP)
     find_library(ELPA_LINK_LIBRARIES
     NAMES elpa_openmp elpa
     HINTS ${ELPA_DIR}
@@ -51,7 +51,7 @@ if(NOT ELPA_INCLUDE_DIRS AND PKG_CONFIG_FOUND)
   if(DEFINED ELPA_DIR)
     string(APPEND CMAKE_PREFIX_PATH ";${ELPA_DIR}")
   endif()
-  if(USE_OPENMP)
+  if(ENABLE_OPENMP)
     pkg_search_module(ELPA REQUIRED IMPORTED_TARGET GLOBAL elpa_openmp)
   else()
     pkg_search_module(ELPA REQUIRED IMPORTED_TARGET GLOBAL elpa)

cmake/modules/FindFFTW3.cmake

@@ -26,7 +26,7 @@ if(ENABLE_FLOAT_FFTW)
 endif()
 
 # Both libfftw3.so and libfftw3_omp.so are required for OpenMP builds.
-if (USE_OPENMP)
+if (ENABLE_OPENMP)
   find_library(FFTW3_OMP_LIBRARY
       NAMES fftw3_omp
       HINTS ${FFTW3_DIR}
@@ -38,7 +38,7 @@ endif()
 # set FFTW3_FOUND to TRUE if all variables are non-zero.
 include(FindPackageHandleStandardArgs)
 set(_fftw3_required_vars FFTW3_LIBRARY FFTW3_INCLUDE_DIR)
-if(USE_OPENMP)
+if(ENABLE_OPENMP)
   list(APPEND _fftw3_required_vars FFTW3_OMP_LIBRARY)
 endif()
 if(ENABLE_FLOAT_FFTW)
@@ -49,7 +49,7 @@ find_package_handle_standard_args(FFTW3 DEFAULT_MSG ${_fftw3_required_vars})
 # Copy the results to the output variables and target.
 if(FFTW3_FOUND)
     set(FFTW3_LIBRARIES ${FFTW3_LIBRARY})
-    if (USE_OPENMP)
+    if (ENABLE_OPENMP)
         list(APPEND FFTW3_LIBRARIES ${FFTW3_OMP_LIBRARY})
     endif()
 
@@ -77,7 +77,7 @@ if(FFTW3_FOUND)
                 IMPORTED_LOCATION "${FFTW3_FLOAT_LIBRARY}"
                 INTERFACE_INCLUDE_DIRECTORIES "${FFTW3_INCLUDE_DIRS}")
     endif()
-    if (USE_OPENMP)
+    if (ENABLE_OPENMP)
         if(NOT TARGET FFTW3::FFTW3_OMP)
         add_library(FFTW3::FFTW3_OMP UNKNOWN IMPORTED)
         set_target_properties(FFTW3::FFTW3_OMP PROPERTIES

cmake/modules/FindKML.cmake

@@ -20,7 +20,7 @@
 #   KML_BLAS_THREADING  kblas variant: auto, multi, locking, or nolocking
 #                        (default: auto)
 #
-# The default threading selection uses the caller's USE_OPENMP option when it
+# The default threading selection uses the caller's ENABLE_OPENMP option when it
 # is available: multi for OpenMP builds and nolocking otherwise. Projects can
 # select a KML_BLAS_THREADING variant explicitly.
 #
@@ -46,7 +46,7 @@ endif()
 
 set(_kml_thread_variants multi locking nolocking)
 if(KML_BLAS_THREADING STREQUAL "auto")
-  if(DEFINED USE_OPENMP AND USE_OPENMP)
+  if(ENABLE_OPENMP)
     set(_kml_blas_threading multi)
   else()
     set(_kml_blas_threading nolocking)

cmake/modules/FindMKL.cmake

@@ -61,7 +61,7 @@ endif()
 # Keep MKL threading internal: derive it from ABACUS OpenMP support and the
 # known compiler/runtime combinations. Unknown OpenMP runtimes use sequential MKL.
 set(_mkl_threading sequential)
-if(USE_OPENMP)
+if(ENABLE_OPENMP)
   if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     set(_mkl_threading gnu_thread)
   elseif(CMAKE_CXX_COMPILER_ID MATCHES "Intel")

docs/advanced/acceleration/cuda.md

@@ -29,7 +29,7 @@ To compile and use ABACUS in CUDA mode, you currently need to have an NVIDIA GPU
 
 Check the [Advanced Installation Options](https://abacus-rtd.readthedocs.io/en/latest/advanced/install.html#build-with-cuda-support) for the installation of CUDA version support.
 
-Setting both USE_ELPA and USE_CUDA to ON does not automatically enable ELPA to run on GPUs. ELPA support for GPUs needs to be enabled when ELPA is compiled. [enable GPU support](https://github.com/marekandreas/elpa/blob/master/documentation/INSTALL.md).
+Setting both `ENABLE_ELPA` and `USE_CUDA` to ON does not automatically enable ELPA to run on GPUs. ELPA support for GPUs needs to be enabled when ELPA is compiled. [enable GPU support](https://github.com/marekandreas/elpa/blob/master/documentation/INSTALL.md).
 
 The ABACUS program will automatically determine whether the current ELPA supports GPU based on the elpa/elpa_configured_options.h header file. Users can also check this header file to determine the GPU support of ELPA in their environment. ELPA introduced a new API elpa_setup_gpu in version 2023.11.001. So if you want to enable ELPA GPU in ABACUS, the ELPA version must be greater than or equal to 2023.11.001.