wip

.clang-tidy

@@ -109,11 +109,13 @@ CheckOptions:
   - key:             modernize-use-noexcept.ReplacementString
     value:           ''
   - key:             modernize-use-noexcept.UseNoexceptFalse
-    value:           '1'
+    value:           'true'
   - key:             modernize-use-nullptr.NullMacros
     value:           'NULL'
   - key:             modernize-use-transparent-functors.SafeMode
-    value:           '1'
+    value:           'true'
+  - key:             modernize-use-using.IgnoreExternC
+    value:           'true'
   - key:             readability-simplify-boolean-expr.ChainedConditionalAssignment
     value:           '0'
   - key:             readability-simplify-boolean-expr.ChainedConditionalReturn

.github/workflows/push_pull.yml

@@ -9,7 +9,7 @@ permissions:
 
 jobs:
   macos:
-    runs-on: macos-13
+    runs-on: macos-14
     if: ${{ github.repository == 'espressomd/espresso' }}
     steps:
       - name: Checkout
@@ -31,6 +31,7 @@ jobs:
           build_procs: 4
           check_procs: 4
           with_ccache: 'true'
+          with_fpe: 'true'
 
   debian:
     runs-on: ubuntu-latest

.gitlab-ci.yml

@@ -69,7 +69,7 @@ style_doxygen:
     - mkdir build
     - cd build
     - cp ../maintainer/configs/maxset.hpp myconfig.hpp
-    - cmake .. -D ESPRESSO_BUILD_WITH_CUDA=ON -D ESPRESSO_BUILD_WITH_GSL=ON -D ESPRESSO_BUILD_WITH_HDF5=ON -D ESPRESSO_BUILD_WITH_SCAFACOS=ON -D ESPRESSO_BUILD_WITH_WALBERLA=ON -D ESPRESSO_BUILD_WITH_WALBERLA_FFT=ON -D ESPRESSO_BUILD_WITH_STOKESIAN_DYNAMICS=ON -D ESPRESSO_BUILD_WITH_CALIPER=ON
+    - cmake .. -D ESPRESSO_BUILD_WITH_CUDA=ON -D ESPRESSO_BUILD_WITH_GSL=ON -D ESPRESSO_BUILD_WITH_HDF5=ON -D ESPRESSO_BUILD_WITH_SCAFACOS=ON -D ESPRESSO_BUILD_WITH_WALBERLA=ON -D ESPRESSO_BUILD_WITH_WALBERLA_FFT=ON -D ESPRESSO_BUILD_WITH_STOKESIAN_DYNAMICS=ON -D ESPRESSO_BUILD_WITH_CALIPER=ON -D ESPRESSO_BUILD_WITH_FPE=ON
     - sh ../maintainer/CI/dox_warnings.sh
   tags:
     - espresso
@@ -132,7 +132,8 @@ no_rotation:
      with_cuda: 'false'
      myconfig: 'no_rotation'
      with_coverage: 'true'
-     with_scafacos: 'true'
+     with_scafacos: 'false'
+     with_fpe: 'true'
      check_skip_long: 'true'
   script:
     - bash maintainer/CI/build_cmake.sh
@@ -148,6 +149,8 @@ fedora:40:
   variables:
      with_cuda: 'false'
      with_gsl: 'false'
+     with_scafacos: 'false'
+     with_fpe: 'true'
      myconfig: 'maxset'
      make_check_python: 'true'
      with_stokesian_dynamics: 'true'
@@ -422,6 +425,7 @@ empty:
      with_scafacos: 'false'
      with_walberla: 'false'
      with_stokesian_dynamics: 'false'
+     with_fpe: 'true'
      with_coverage: 'false'
      with_coverage_python: 'true'
   script:

CMakeLists.txt

@@ -59,6 +59,7 @@ include(GNUInstallDirs)
 include(FetchContent)
 include(espresso_option_enum)
 include(espresso_enable_avx2_support)
+include(espresso_override_clang_tidy_checks)
 
 if(EXISTS "${PROJECT_BINARY_DIR}/CMakeLists.txt")
   message(
@@ -93,7 +94,7 @@ set(FETCHCONTENT_UPDATES_DISCONNECTED ON)
 FetchContent_Declare(
   walberla
   GIT_REPOSITORY https://i10git.cs.fau.de/walberla/walberla.git
-  GIT_TAG        b0842e1a493ce19ef1bbb8d2cf382fc343970a7f
+  GIT_TAG        f36fa0a68bae59f0b516f6587ea8fa7c24a41141
 )
 FetchContent_Declare(
   stokesian_dynamics
@@ -103,7 +104,7 @@ FetchContent_Declare(
 FetchContent_Declare(
   caliper
   GIT_REPOSITORY https://github.com/LLNL/Caliper.git
-  GIT_TAG        v2.10.0
+  GIT_TAG        v2.12.0
 )
 # cmake-format: on
 
@@ -129,6 +130,8 @@ option(ESPRESSO_BUILD_BENCHMARKS "Enable benchmarks" OFF)
 option(ESPRESSO_BUILD_WITH_VALGRIND "Build with Valgrind instrumentation" OFF)
 option(ESPRESSO_BUILD_WITH_CALIPER "Build with Caliper instrumentation" OFF)
 option(ESPRESSO_BUILD_WITH_CPPCHECK "Run Cppcheck during compilation" OFF)
+option(ESPRESSO_BUILD_WITH_FPE
+       "Build with floating-point exceptions instrumentation" OFF)
 if(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
   option(ESPRESSO_BUILD_WITH_CLANG_TIDY "Run Clang-Tidy during compilation" OFF)
 endif()
@@ -258,7 +261,7 @@ endif()
 # Python interpreter and Cython interface library
 if(ESPRESSO_BUILD_WITH_PYTHON)
   find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development NumPy)
-  find_package(Cython 0.29.28...<3.0.10 REQUIRED)
+  find_package(Cython 0.29.28...<3.0.12 REQUIRED)
   find_program(IPYTHON_EXECUTABLE NAMES jupyter ipython3 ipython)
 endif()
 
@@ -581,6 +584,33 @@ if(ESPRESSO_BUILD_WITH_CLANG_TIDY)
   find_package(ClangTidy "${CMAKE_CXX_COMPILER_VERSION}" EXACT REQUIRED)
   set(ESPRESSO_CXX_CLANG_TIDY "${CLANG_TIDY_EXE}")
   set(ESPRESSO_CUDA_CLANG_TIDY "${CLANG_TIDY_EXE};--extra-arg=--cuda-host-only")
+  set(SKIP_CLANG_TIDY_CHECKS "")
+  set(SKIP_CLANG_TIDY_CHECKS_CXX "")
+  set(SKIP_CLANG_TIDY_CHECKS_CUDA "")
+  if(ESPRESSO_BUILD_WITH_CALIPER)
+    # Clang-Tidy sometimes emits diagnostics in code enclosed in `extern "C"`
+    # that are not always actionable, since they may rely on keywords only
+    # available in the C++ language. While some checks have an extra flag
+    # 'IgnoreExternC' to disable them inside C code, not all affected checks
+    # have been fixed yet. For an in-depth discussion on this topic, see
+    # https://github.com/llvm/llvm-project/issues/35272
+    list(APPEND SKIP_CLANG_TIDY_CHECKS "-modernize-use-auto")
+    list(APPEND SKIP_CLANG_TIDY_CHECKS "-modernize-use-nullptr")
+    list(APPEND SKIP_CLANG_TIDY_CHECKS "-modernize-deprecated-headers")
+  endif()
+  if(ESPRESSO_BUILD_WITH_CUDA)
+    # silence casts in cuda_runtime.h (for both C++ and CUDA source files)
+    list(APPEND SKIP_CLANG_TIDY_CHECKS "-bugprone-casting-through-void")
+    # silence nullptr dereference in cuda::thrust
+    list(APPEND SKIP_CLANG_TIDY_CHECKS_CUDA
+         "-clang-analyzer-core.NonNullParamChecker")
+  endif()
+  espresso_override_clang_tidy_checks(
+    ESPRESSO_CXX_CLANG_TIDY "${SKIP_CLANG_TIDY_CHECKS}"
+    "${SKIP_CLANG_TIDY_CHECKS_CXX}")
+  espresso_override_clang_tidy_checks(
+    ESPRESSO_CUDA_CLANG_TIDY "${SKIP_CLANG_TIDY_CHECKS}"
+    "${SKIP_CLANG_TIDY_CHECKS_CUDA}")
 endif()
 
 if(ESPRESSO_BUILD_WITH_CPPCHECK)
@@ -684,9 +714,13 @@ if(ESPRESSO_BUILD_WITH_CALIPER)
   set(CALIPER_WITH_NVTX off CACHE BOOL "")
   set(CALIPER_WITH_CUPTI off CACHE BOOL "")
   set(CALIPER_BUILD_SHARED_LIBS on CACHE BOOL "")
+  set(CALIPER_INSTALL_CONFIG off CACHE BOOL "")
+  set(CALIPER_INSTALL_HEADERS off CACHE BOOL "")
   if(NOT caliper_POPULATED)
     FetchContent_MakeAvailable(caliper)
   endif()
+  target_compile_options(
+    caliper-common PRIVATE $<$<CXX_COMPILER_ID:GNU>:-Wno-restrict>)
   target_compile_options(
     caliper-services
     PRIVATE
@@ -696,6 +730,7 @@ if(ESPRESSO_BUILD_WITH_CALIPER)
     PRIVATE $<$<CXX_COMPILER_ID:GNU>:-Wno-maybe-uninitialized>
             $<$<CXX_COMPILER_ID:GNU>:-Wno-volatile>
             $<$<CXX_COMPILER_ID:Clang,AppleClang>:-Wno-deprecated-volatile>)
+  set_target_properties(caliper-runtime PROPERTIES CXX_CLANG_TIDY "")
 endif()
 
 #

cmake/espresso_cmake_config.cmakein

@@ -21,6 +21,8 @@
 
 #cmakedefine ESPRESSO_BUILD_WITH_CALIPER
 
+#cmakedefine ESPRESSO_BUILD_WITH_FPE
+
 #define PACKAGE_NAME "${PROJECT_NAME}"
 
 /**

cmake/espresso_override_clang_tidy_checks.cmake

@@ -0,0 +1,64 @@
+#
+# Copyright (C) 2024 The ESPResSo project
+#
+# This file is part of ESPResSo.
+#
+# ESPResSo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ESPResSo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+# Override Clang-Tidy checks.
+#
+# This function appends an extra flag "--checks=..." in the parent scope
+# variable whose name is passed as first argument. The second and third
+# arguments are the general and the language-specific overrides, respectively.
+# This way you can append a common set of overrides plus language-specific
+# overrides in two variables named MYPROJECT_CXX_CLANG_TIDY and
+# MYPROJECT_CUDA_CLANG_TIDY, which are used to set the CXX_CLANG_TIDY and
+# CUDA_CLANG_TIDY properties of CMake targets.
+#
+# Example:
+# ```cmake
+# include(espresso_override_clang_tidy_checks)
+# if(MYPROJECT_BUILD_WITH_CLANG_TIDY)
+#   find_package(ClangTidy "${CMAKE_CXX_COMPILER_VERSION}" EXACT REQUIRED)
+#   set(MYPROJECT_CXX_CLANG_TIDY "${CLANG_TIDY_EXE}")
+#   set(MYPROJECT_CUDA_CLANG_TIDY "${CLANG_TIDY_EXE};--extra-arg=--cuda-host-only")
+#   set(SKIP_CLANG_TIDY_CHECKS "")
+#   set(SKIP_CLANG_TIDY_CHECKS_CXX "")
+#   set(SKIP_CLANG_TIDY_CHECKS_CUDA "")
+#   # silence false positives in code enclosed in `extern "C" { /* ... */ }`
+#   list(APPEND SKIP_CLANG_TIDY_CHECKS "-modernize-use-auto")
+#   if (MYPROJECT_BUILD_WITH_CUDA)
+#     # silence casts in cuda_runtime.h (for both C++ and CUDA source files)
+#     list(APPEND SKIP_CLANG_TIDY_CHECKS "-bugprone-casting-through-void")
+#     # silence nullptr dereference in cuda::thrust (only for CUDA files)
+#     list(APPEND SKIP_CLANG_TIDY_CHECKS_CUDA "-clang-analyzer-core.NonNullParamChecker")
+#   endif()
+#   espresso_override_clang_tidy_checks(MYPROJECT_CXX_CLANG_TIDY "${SKIP_CLANG_TIDY_CHECKS}" "${SKIP_CLANG_TIDY_CHECKS_CXX}")
+#   espresso_override_clang_tidy_checks(MYPROJECT_CUDA_CLANG_TIDY "${SKIP_CLANG_TIDY_CHECKS}" "${SKIP_CLANG_TIDY_CHECKS_CUDA}")
+#   set_target_properties(myproject_core PROPERTIES CXX_CLANG_TIDY "${MYPROJECT_CXX_CLANG_TIDY}")
+#   set_target_properties(myproject_cuda PROPERTIES CUDA_CLANG_TIDY "${MYPROJECT_CUDA_CLANG_TIDY}")
+# endif()
+# ```
+
+function(espresso_override_clang_tidy_checks)
+  set(VARNAME "${ARGV0}")
+  set(CHECKS "${ARGV1}")
+  set(CHECKS_LANG "${ARGV2}")
+  list(APPEND CHECKS ${CHECKS_LANG})
+  if(CHECKS)
+    list(JOIN CHECKS "," CHECKS_STRING)
+    set(${VARNAME} "${${VARNAME}};--checks=${CHECKS_STRING}" PARENT_SCOPE)
+  endif()
+endfunction()

doc/bibliography.bib

@@ -45,6 +45,18 @@ @Article{andersen83a
   doi       = {10.1016/0021-9991(83)90014-1},
 }
 
+@TechReport{ARM-DDI-0487-2024,
+author = {{Arm Limited}},
+title = {Arm Architecture Reference Manual for {A}-profile architecture},
+type = {Manual},
+number = {ARM DDI 0487},
+month = nov,
+year = {2024},
+address = {Cambridge, England},
+institution = {Arm Limited},
+url = {https://developer.arm.com/documentation/ddi0487/latest/},
+}
+
 @Article{arnold02a,
   author = {Arnold, Axel and Holm, Christian},
   title = {{MMM2D}: {A} fast and accurate summation method for electrostatic interactions in {2D} slab geometries},
@@ -598,6 +610,31 @@ @Article{humphrey96a
   doi = {10.1016/0263-7855(96)00018-5},
 }
 
+@TechReport{ISO-EIC-60559-2020,
+author = {{International Organization for Standardization} and {International Electrotechnical Commission} and {Institute of Electrical and Electronics Engineers}},
+title = {International Standard -- Floating-point arithmetic},
+type = {Standard},
+number = {{ISO}/{IEC} 60559:2020({E}), {IEEE} Std 754-2019},
+month = may,
+year = {2020},
+edition = {2nd},
+isbn = {978-1-5044-6641-7},
+doi = {10.1109/IEEESTD.2020.9091348},
+}
+
+@TechReport{ISO-EIC-9899-1999,
+author = {{International Organization for Standardization} and {International Electrotechnical Commission}},
+title = {Information technology --- Programming languages --- {C}},
+type = {Standard},
+number = {{ISO}/{IEC} 9899:1999},
+month = dec,
+year = {1999},
+edition = {2nd},
+address = {Geneva, Switzerland},
+institution = {International Organization for Standardization},
+url = {https://www.iso.org/standard/29237.html},
+}
+
 @Article{jancigova16a,
 author = {Jan\v{c}igov\'{a}, Iveta and Cimr\'{a}k, Ivan},
 title = {Non-uniform force allocation for area preservation in spring network models},

doc/sphinx/running.rst

@@ -516,6 +516,11 @@ you can as a last resort activate sanitizers:
 The resulting build will be around 5 times slower that a debug build,
 but it will generate valuable reports when detecting fatal exceptions.
 
+If you are dealing with non-finite math errors (infinity, NaN, etc.),
+you can interrupt code execution at the first occurence of a non-finite
+value using :ref:`floating-point exceptions <FPE>` and investigate
+the failing mathematical operation in GDB.
+
 It is possible to attach an external debugger to ``pypresso``, albeit with
 a custom syntax. The ``pypresso`` executable file is actually not a program
 but a script which sets the Python path appropriately and starts the Python
@@ -734,6 +739,12 @@ tool. It detects memory leaks and bugs caused by dangling references.
 
 For more details, please consult the tool online documentation [5]_.
 
+On some releases of the Linux kernel, ASAN fails to initialize when running
+the executable due to address space layout randomization (ASLR) [10]_.
+On affected environments, one can temporarily reduce the entropy via
+``sudo sysctl vm.mmap_rnd_bits=28`` (default is usually 32 bits)
+for the time of the ASAN analysis, and then revert back to the default value.
+
 .. _UBSAN:
 
 UBSAN
@@ -750,6 +761,59 @@ array accesses out of bounds, signed integer overflows, etc.
 
 For more details, please consult the tool online documentation [6]_.
 
+.. _FPE:
+
+FPE
+~~~
+
+.. note::
+
+    Requires specific compiler and linker flags, enabled with the CMake option
+    ``-D ESPRESSO_BUILD_WITH_FPE=ON -D CMAKE_BUILD_TYPE=RelWithDebInfo``.
+
+When abnormal mathematical operations take place at runtime,
+for example divisions by zero, multiplication of infinity with zero,
+square roots and logarithms of negative numbers, overflows, underflows,
+or conversion of NaN values to integers, CPU flags may be raised.
+The flags are known as *CPU exceptions*, and can be queried to detect
+if a past operation yielded an abnormal result. They can be unmasked
+to automatically *trap*, i.e. leave the user space and enter kernel space,
+where the operating system will run a callback function, which may send
+a POSIX signal such as ``SIGFPE`` or ``SIGILL``. Those signals can be
+captured by a user-defined *signal handler*, which takes the form of a
+C++ function with strict restrictions on which operations it can execute,
+and are typically assigning an integer into a global variable for debugging.
+Execution then resumes in user space on the exact same instruction that
+originally trapped, potentially entering an infinite loop.
+
+C libraries like GNU libc provide support for floating-point exceptions
+(FPE or FE). These can be unmasked to interrupt |es| on the first occurrence
+of an abnormal floating-point operation. This is achieved by sending a signal
+that can be caught in GDB to allow inspection of the failing code.
+
+When FPE instrumentation is enabled, most script interface calls will be
+monitored for abnormal mathematical operations. One can select which subset
+of CPU exceptions will trap by explicitly providing a bitmask to the FPE
+handler constructor, like so:
+
+.. code-block:: c++
+
+    Variant ObjectHandle::call_method(const std::string &name,
+                                      const VariantMap &params) {
+      if (m_context)
+        m_context->notify_call_method(this, name, params);
+
+    #ifdef FPE
+      auto const trap = fe_trap::make_shared_scoped(FE_DIVBYZERO | FE_INVALID);
+    #endif
+      return this->do_call_method(name, params);
+    }
+
+For more details, see annex F IEC 60559 "floating-point arithmetic"
+in ISO/EIC 9899 :cite:`ISO-EIC-9899-1999` and chapter 7
+"Exceptions and default exception handling" in
+ISO/IEC 60559:2020(E) :cite:`ISO-EIC-60559-2020`.
+
 .. _Caliper:
 
 Caliper
@@ -871,8 +935,8 @@ graph that can be converted to a static graph using ``gprof2dot`` and ``dot``:
     dot -Tpdf ${callgrind_out}.dot -o ${callgrind_out}.pdf
 
 The Valgrind output file generally follows the pattern ``callgrind.out.pid``,
-where ``pid`` is the actualy process id. The ``${callgrind_out}`` variable
-is populated with the return value of a subshell commands that finds the most
+where ``pid`` is the actual process id. The ``${callgrind_out}`` variable
+is populated with the return value of a subshell command that finds the most
 recent output file that matches that pattern.
 
 It is also possible to open the output file in KCachegrind [4]_ to browse
@@ -1087,3 +1151,6 @@ ____
 
 .. [9]
    https://docs.nvidia.com/compute-sanitizer/ComputeSanitizer/index.html
+
+.. [10]
+   https://github.com/google/sanitizers/issues/1614