MLIP and Water Tutorial

.clang-tidy

@@ -43,9 +43,10 @@ Checks: |
    readability-function-size'
 WarningsAsErrors: '*,-clang-analyzer-core.StackAddrEscapeBase,-clang-analyzer-optin.mpi.MPI-Checker'
 HeaderFilterRegex: '.*'
+ExcludeHeaderFilterRegex: '^/usr/'
 FormatStyle:     none
 User: espresso
-CheckOptions:    
+CheckOptions:
   - key:             bugprone-argument-comment.StrictMode
     value:           '0'
   - key:             bugprone-assert-side-effect.AssertMacros

.github/workflows/push_pull.yml

@@ -57,7 +57,7 @@ jobs:
   debian:
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/espressomd/docker/debian:b858760d11a10767efa9e8b28b9a7fbfcf899e3a-base-layer
+      image: ghcr.io/espressomd/docker/debian:3388b293a5e8a9b613b1bfa4220e54dfb4bff245-base-layer
       credentials:
          username: ${{ github.actor }}
          password: ${{ secrets.github_token }}
@@ -99,7 +99,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.repository == 'espressomd/espresso' }}
     container:
-      image: ghcr.io/espressomd/docker/ubuntu-wo-dependencies:b858760d11a10767efa9e8b28b9a7fbfcf899e3a-base-layer
+      image: ghcr.io/espressomd/docker/ubuntu-wo-dependencies:3388b293a5e8a9b613b1bfa4220e54dfb4bff245-base-layer
       credentials:
          username: ${{ github.actor }}
          password: ${{ secrets.github_token }}
@@ -141,7 +141,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.repository == 'espressomd/espresso' }}
     container:
-      image: ghcr.io/espressomd/docker/fedora:b858760d11a10767efa9e8b28b9a7fbfcf899e3a-base-layer
+      image: ghcr.io/espressomd/docker/fedora:3388b293a5e8a9b613b1bfa4220e54dfb4bff245-base-layer
       credentials:
          username: ${{ github.actor }}
          password: ${{ secrets.github_token }}

.gitlab-ci.yml

@@ -1,4 +1,4 @@
-image: ghcr.io/espressomd/docker/ubuntu:b858760d11a10767efa9e8b28b9a7fbfcf899e3a
+image: ghcr.io/espressomd/docker/ubuntu:3388b293a5e8a9b613b1bfa4220e54dfb4bff245
 
 stages:
   - prepare
@@ -16,7 +16,7 @@ stages:
 
 .notification_job_template: &notification_job_definition
   <<: *global_job_definition
-  image: ghcr.io/espressomd/docker/fedora:b858760d11a10767efa9e8b28b9a7fbfcf899e3a
+  image: ghcr.io/espressomd/docker/alpine:3388b293a5e8a9b613b1bfa4220e54dfb4bff245
   variables:
     GET_SOURCES_ATTEMPTS: 3
   dependencies: []

cmake/FindCUDACompilerClang.cmake

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2009-2022 The ESPResSo project
+# Copyright (C) 2009-2025 The ESPResSo project
 # Copyright (C) 2009,2010
 #   Max-Planck-Institute for Polymer Research, Theory Group
 #
@@ -80,41 +80,6 @@ if(NOT CMAKE_CUDA_FLAGS MATCHES "-Wno-unknown-cuda-version")
 endif()
 message(STATUS "Found CUDA toolkit installation: ${ESPRESSO_CLANG_DETECTED_CUDA_DIR} (recognized by ${CMAKE_CUDA_COMPILER_ID} as CUDA ${ESPRESSO_CLANG_DETECTED_CUDA_VERSION})")
 
-target_compile_options(
-  espresso_cuda_flags
-  INTERFACE
-  $<$<CONFIG:Debug>:-g>
-  $<$<CONFIG:Release>:-O3 -DNDEBUG>
-  $<$<CONFIG:MinSizeRel>:-O2 -DNDEBUG>
-  $<$<CONFIG:RelWithDebInfo>:-O2 -g -DNDEBUG>
-  $<$<CONFIG:Coverage>:-O3 -g -fprofile-instr-generate -fcoverage-mapping>
-  $<$<CONFIG:RelWithAssert>:-O3 -g>
-)
-
-function(espresso_configure_gpu_target)
-  cmake_parse_arguments(TARGET "" "NAME" "SOURCES" ${ARGN})
-  set_source_files_properties(${TARGET_SOURCES} PROPERTIES LANGUAGE "CUDA")
-  set_target_properties(${TARGET_NAME} PROPERTIES LINKER_LANGUAGE "CXX")
-  target_link_libraries(${TARGET_NAME} PRIVATE espresso::cuda_flags)
-endfunction()
-
-function(espresso_add_gpu_library)
-  add_library(${ARGV})
-  cmake_parse_arguments(ARG "STATIC;SHARED;MODULE;EXCLUDE_FROM_ALL" "" "" ${ARGN})
-  list(GET ARGV 0 TARGET_NAME)
-  set(TARGET_SOURCES ${ARG_UNPARSED_ARGUMENTS})
-  list(POP_FRONT TARGET_SOURCES)
-  espresso_configure_gpu_target(NAME ${TARGET_NAME} SOURCES ${TARGET_SOURCES})
-endfunction()
-
-function(espresso_add_gpu_executable)
-  add_executable(${ARGV})
-  list(GET ARGV 0 TARGET_NAME)
-  set(TARGET_SOURCES ${ARGV})
-  list(POP_FRONT TARGET_SOURCES)
-  espresso_configure_gpu_target(NAME ${TARGET_NAME} SOURCES ${TARGET_SOURCES})
-endfunction()
-
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(
   CUDACompilerClang REQUIRED_VARS CMAKE_CUDA_COMPILER VERSION_VAR

cmake/FindCUDACompilerNVCC.cmake

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2009-2022 The ESPResSo project
+# Copyright (C) 2009-2025 The ESPResSo project
 # Copyright (C) 2009,2010
 #   Max-Planck-Institute for Polymer Research, Theory Group
 #
@@ -25,37 +25,6 @@
 set(CUDA_LINK_LIBRARIES_KEYWORD PUBLIC)
 set(CUDA_PROPAGATE_HOST_FLAGS OFF)
 
-target_compile_options(
-  espresso_cuda_flags
-  INTERFACE
-  $<$<CONFIG:Debug>:-g -G>
-  $<$<CONFIG:Release>:-Xptxas=-O3 -Xcompiler=-O3 -DNDEBUG>
-  $<$<CONFIG:MinSizeRel>:-Xptxas=-O2 -Xcompiler=-Os -DNDEBUG>
-  $<$<CONFIG:RelWithDebInfo>:-Xptxas=-O2 -Xcompiler=-O2,-g -DNDEBUG>
-  $<$<CONFIG:Coverage>:-Xptxas=-O3 -Xcompiler=-Og,-g,--coverage,-fprofile-abs-path>
-  $<$<CONFIG:RelWithAssert>:-Xptxas=-O3 -Xcompiler=-O3,-g>
-  $<$<BOOL:${CMAKE_OSX_SYSROOT}>:-Xcompiler=-isysroot;-Xcompiler=${CMAKE_OSX_SYSROOT}>
-  # workaround for https://github.com/espressomd/espresso/issues/4943
-  $<$<BOOL:${ESPRESSO_BUILD_WITH_CCACHE}>:$<$<CONFIG:Coverage>:--coverage -fprofile-abs-path>>
-)
-
-function(espresso_configure_gpu_target)
-  set(TARGET_NAME ${ARGV0})
-  set_target_properties(${TARGET_NAME} PROPERTIES CUDA_SEPARABLE_COMPILATION ON)
-  target_link_libraries(${TARGET_NAME} PRIVATE espresso::cuda_flags $<$<CONFIG:Coverage>:gcov>)
-  espresso_add_cuda_rpaths(${TARGET_NAME})
-endfunction()
-
-function(espresso_add_gpu_library)
-  add_library(${ARGV})
-  espresso_configure_gpu_target(${ARGV0})
-endfunction()
-
-function(espresso_add_gpu_executable)
-  add_executable(${ARGV})
-  espresso_configure_gpu_target(${ARGV0})
-endfunction()
-
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(
   CUDACompilerNVCC REQUIRED_VARS CMAKE_CUDA_COMPILER VERSION_VAR

cmake/espresso_unit_test.cmake

@@ -19,44 +19,45 @@
 
 # generate a test name based on the file name
 function(espresso_unit_test_make_name)
-  cmake_parse_arguments(TEST "" "SRC;NAME" "" ${ARGN})
+  cmake_parse_arguments(TEST "" "SRC;NAME;SUFFIX" "" ${ARGN})
   if(NOT DEFINED TEST_NAME)
     cmake_path(GET TEST_SRC STEM TEST_NAME)
     set(TEST_NAME ${TEST_NAME} PARENT_SCOPE)
+    if(DEFINED TEST_SUFFIX)
+      set(TEST_NAME ${TEST_NAME}_${TEST_SUFFIX} PARENT_SCOPE)
+    endif()
+  elseif(DEFINED TEST_SUFFIX)
+    message(FATAL_ERROR "Cannot provide both a NAME and SUFFIX (test: ${TEST_SRC})")
   endif()
 endfunction()
 
 # create the executable of a unit test
 function(espresso_unit_test_executable)
-  cmake_parse_arguments(TEST "" "SRC;NAME;NUM_PROC;NUM_THREADS" "DEPENDS" ${ARGN})
-  espresso_unit_test_make_name(SRC ${TEST_SRC} NAME ${TEST_NAME})
-  if(${TEST_SRC} MATCHES ".*\.cu$")
-    espresso_add_gpu_executable(${TEST_NAME} ${TEST_SRC})
-  else()
-    add_executable(${TEST_NAME} ${TEST_SRC})
+  cmake_parse_arguments(TEST "" "SRC;NAME;SUFFIX;NUM_PROC;NUM_THREADS" "DEPENDS" ${ARGN})
+  if(DEFINED TEST_UNPARSED_ARGUMENTS)
+    message(FATAL_ERROR "Cannot parse arguments ${TEST_UNPARSED_ARGUMENTS}")
   endif()
+  espresso_unit_test_make_name(${ARGV})
+  add_executable(${TEST_NAME} ${TEST_SRC})
   espresso_set_common_target_properties(${TEST_NAME})
   # Build tests only when testing
   set_target_properties(${TEST_NAME} PROPERTIES EXCLUDE_FROM_ALL ON)
-  target_link_libraries(${TEST_NAME} PRIVATE Boost::unit_test_framework)
-  if(TEST_DEPENDS)
-    target_link_libraries(${TEST_NAME} PRIVATE ${TEST_DEPENDS})
-  endif()
+  target_link_libraries(
+    ${TEST_NAME} PRIVATE Boost::unit_test_framework espresso::config
+    espresso::compiler_flags espresso::tests::compiler_flags ${TEST_DEPENDS})
   target_include_directories(${TEST_NAME} PRIVATE ${CMAKE_SOURCE_DIR}/src/core)
-  if(${TEST_SRC} MATCHES ".*\.cu$")
-    target_link_libraries(${TEST_NAME} PRIVATE espresso::config CUDA::cudart)
-  else()
-    target_link_libraries(${TEST_NAME} PRIVATE espresso::config espresso::cpp_flags espresso::tests::cpp_flags)
-  endif()
   if(ESPRESSO_BUILD_WITH_CUDA)
     espresso_add_cuda_rpaths(${TEST_NAME}) # for GPU-aware MPI vendors
   endif()
 endfunction()
 
 # register the executable of a unit test in the CTest suite
 function(espresso_unit_test_register)
-  cmake_parse_arguments(TEST "" "SRC;NAME;NUM_PROC;NUM_THREADS;TARGET" "DEPENDS" ${ARGN})
-  espresso_unit_test_make_name(SRC ${TEST_SRC} NAME ${TEST_NAME})
+  cmake_parse_arguments(TEST "" "SRC;NAME;SUFFIX;NUM_PROC;NUM_THREADS;TARGET" "DEPENDS" ${ARGN})
+  if(DEFINED TEST_UNPARSED_ARGUMENTS)
+    message(FATAL_ERROR "Cannot parse arguments ${TEST_UNPARSED_ARGUMENTS}")
+  endif()
+  espresso_unit_test_make_name(${ARGV})
   if(NOT DEFINED TEST_TARGET)
     set(TEST_TARGET ${TEST_NAME})
   endif()
@@ -66,8 +67,8 @@ function(espresso_unit_test_register)
       set(TEST_NUM_PROC ${ESPRESSO_TEST_NP})
     endif()
     espresso_set_mpiexec_tmpdir(${TEST_NAME})
-    add_test(NAME ${TEST_NAME} COMMAND ${MPIEXEC} ${ESPRESSO_MPIEXEC_PREFLAGS}
-             ${MPIEXEC_NUMPROC_FLAG} ${TEST_NUM_PROC} ${MPIEXEC_PREFLAGS}
+    add_test(NAME ${TEST_NAME} COMMAND ${MPIEXEC} ${MPIEXEC_PREFLAGS}
+             ${ESPRESSO_MPIEXEC_PREFLAGS} ${MPIEXEC_NUMPROC_FLAG} ${TEST_NUM_PROC}
              ${ESPRESSO_MPIEXEC_TMPDIR} ${CMAKE_CURRENT_BINARY_DIR}/${TEST_TARGET}
              ${MPIEXEC_POSTFLAGS})
   else()
@@ -97,9 +98,11 @@ function(espresso_unit_test_register)
     math(EXPR TEST_NUM_CORES "${TEST_NUM_CORES} * ${TEST_NUM_THREADS}")
   endif()
   set_tests_properties(
-    ${TEST_NAME} PROPERTIES ENVIRONMENT "${TEST_ENV_VARIABLES}" PROCESSORS ${TEST_NUM_CORES})
+    ${TEST_NAME} PROPERTIES ENVIRONMENT "${TEST_ENV_VARIABLES}"
+                            PROCESSORS ${TEST_NUM_CORES}
+                            LABELS "unit_test")
 
-  add_dependencies(check_unit_tests ${TEST_TARGET})
+  add_dependencies(unit_tests_executables ${TEST_TARGET})
 endfunction()
 
 # create the executable of a unit test and register it in the CTest suite

doc/bibliography.bib

@@ -271,9 +271,22 @@ @Article{brown95a
   publisher={Taylor \& Francis},
 }
 
+@Article{buyl14a,
+  title = {{H5MD}: {A} structured, efficient, and portable file format for molecular data},
+  author = {de Buyl, Pierre and Colberg, Peter H. and H{\"o}fling, Felix},
+  journal = {Computer Physics Communications},
+  number = {6},
+  volume = {185},
+  year = {2014},
+  pages = {1546--1553},
+  doi = {10.1016/j.cpc.2014.01.018},
+  publisher = {Elsevier},
+  issn = {0010-4655},
+}
+
 @Article{cerda08d,
   title                    = {{P3M} algorithm for dipolar interactions},
-  author                   = {Cerd\`{a}, Juan J. and Ballenegger, Vincent and Lenz, Olaf and Holm, Christian},
+  author                   = {Cerd{\`a}, Juan J. and Ballenegger, Vincent and Lenz, Olaf and Holm, Christian},
   journal                  = {The Journal of Chemical Physics},
   year                     = {2008},
   pages                    = {234104},
@@ -398,6 +411,18 @@ @Article{deserno98b
   doi = {10.1063/1.477415},
 }
 
+@TechReport{devresse24a,
+  author       = {Devresse, Adrien and Cornu, Nicolas and Grosheintz-Laval, Luc and Awile, Omar and
+                  de Geus, Tom and Pereira, Fernando and Wolf, Matthias and {HighFive Contributors}},
+  title        = {{HighFive} - Header-only {C++} {HDF5} interface},
+  month        = dec,
+  year         = 2024,
+  institution  = {Blue Brain Project},
+  type         = {Software release},
+  number       = {v2.10.1},
+  doi          = {10.5281/zenodo.14272664},
+}
+
 @Article{dhumieres09a,
   title                    = {Viscosity independent numerical errors for {L}attice {B}oltzmann models: from recurrence equations to ``magic'' collision numbers},
   author                   = {d'Humi{\`e}res, Dominique and Ginzburg, Irina},
@@ -903,6 +928,13 @@ @TechReport{misc-cuda-gdb
   url         = {https://docs.nvidia.com/cuda/pdf/cuda-gdb.pdf},
 }
 
+@Misc{misc-hdf5,
+author = {{The HDF Group}},
+title = {{Hierarchical Data Format}, version~5},
+howpublished = {GitHub},
+url = {https://github.com/HDFGroup/hdf5},
+}
+
 @Misc{misc-kernprof,
   author    = {Kern, Robert and Crall, Jon and Olsen, Brett and {OpenPyUtils community contributors}},
   title     = {{line_profiler} and {kernprof}},

doc/sphinx/installation.rst

@@ -641,24 +641,33 @@ They are added by CMake if the corresponding dependency was found on the
 system. Some of these external features are optional and must be activated
 using a CMake flag (see :ref:`Options and Variables`).
 
-- ``CUDA`` Enables GPU-specific features.
+- ``CUDA``: enable offloading to Nvidia GPUs for features that support it
+  (see :ref:`CUDA acceleration`)
 
-- ``FFTW`` Enables features relying on the fast Fourier transforms, e.g. P3M.
+- ``FFTW``: enables features relying on the fast Fourier transforms,
+  such as the P3M method (see :ref:`Coulomb P3M` and :ref:`Dipolar P3M`)
 
-- ``H5MD`` Write data to H5MD-formatted hdf5 files (see :ref:`Writing H5MD-files`)
+- ``H5MD``: enable parallel input/output to hdf5 files with H5MD specification
+  (see :ref:`Writing hdf5 files`)
 
-- ``SCAFACOS`` Enables features relying on the ScaFaCoS library (see
+- ``WALBERLA``: enable continuum-based solvers: lattice-Boltzmann method,
+  diffusion-advection-reaction equations solver, and Poisson equation solver
+  if ``FFTW`` is enabled (see :ref:`Lattice-Boltzmann` and :ref:`Electrokinetics`)
+
+- ``SCAFACOS``: enables features from the ScaFaCoS library (see
   :ref:`ScaFaCoS electrostatics`, :ref:`ScaFaCoS magnetostatics`).
 
-- ``GSL`` Enables features relying on the GNU Scientific Library, e.g.
+- ``GSL``: enables features relying on the GNU Scientific Library, e.g.
   :meth:`espressomd.cluster_analysis.Cluster.fractal_dimension`.
 
-- ``STOKESIAN_DYNAMICS`` Enables the Stokesian Dynamics feature
+- ``STOKESIAN_DYNAMICS``: enable the Stokesian Dynamics propagator
   (see :ref:`Stokesian Dynamics`). Requires BLAS and LAPACK.
 
-- ``SHARED_MEMORY_PARALLELISM`` Enables shared-memory parallelism.
-
+- ``SHARED_MEMORY_PARALLELISM``: enable shared-memory parallelism
+  (OpenMP, Kokkos, Cabana)
 
+- ``CALIPER``, ``VALGRIND``, ``FPE``: enable various instrumentation tools
+  (see :ref:`Instrumentation`)
 
 .. _Configuring:
 
@@ -926,32 +935,11 @@ The repository URLs can be found in the ``GIT_REPOSITORY`` field of the
 corresponding ``FetchContent_Declare()`` commands. The ``GIT_TAG`` field
 provides the commit. Clone these repositories locally and edit the |es|
 build system such that ``GIT_REPOSITORY`` points to the absolute path of
-the clone. You can automate this task by adapting the following commands:
-
-* ``ESPRESSO_BUILD_WITH_WALBERLA``
-
-  .. code-block:: bash
-
-    sed -ri 's|GIT_REPOSITORY +.+/walberla.git|GIT_REPOSITORY /work/username/walberla|' CMakeLists.txt
-
-* ``ESPRESSO_BUILD_WITH_HDF5``
-
-  .. code-block:: bash
+the clone. You can automate this text substitution by adapting the following command:
 
-    sed -ri 's|GIT_REPOSITORY +.+h5xx.git|GIT_REPOSITORY /work/username/h5xx|' CMakeLists.txt
-
-* ``ESPRESSO_BUILD_WITH_STOKESIAN_DYNAMICS``
-
-  .. code-block:: bash
-
-    sed -ri 's|GIT_REPOSITORY +.+stokesian-dynamics.git|GIT_REPOSITORY /work/username/stokesian_dynamics|' CMakeLists.txt
-
-* ``ESPRESSO_BUILD_WITH_CALIPER``
-
-  .. code-block:: bash
-
-    sed -ri 's|GIT_REPOSITORY +.+/Caliper.git|GIT_REPOSITORY /work/username/caliper|' CMakeLists.txt
+.. code-block:: bash
 
+   sed -ri 's|GIT_REPOSITORY +.+/([^/]+).git|GIT_REPOSITORY /work/username/\1|' CMakeLists.txt
 
 Compiling, testing and installing
 ---------------------------------