KOKKOS: bug fixes and test coverage for the KOKKOS package

cmake/CMakeLists.txt

@@ -901,6 +901,13 @@ install(
   DESTINATION ${CMAKE_INSTALL_SYSCONFDIR}/profile.d
 )
 
+###############################################################################
+# On Linux systems (any others, too?) we may need to update the shared linker cache
+###############################################################################
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+  install(CODE "execute_process(COMMAND ldconfig || exit 0)")
+endif()
+
 ###############################################################################
 # Install LAMMPS lib and python module into site-packages folder with
 # "install-python" target.  Behaves exactly like "make install-python" for
@@ -939,7 +946,6 @@ add_custom_target(tarball
   COMMAND ${LAMMPS_DIR}/cmake/packaging/build_tarball.sh ${LAMMPS_DIR}/doc
 )
 
-
 include(Testing)
 include(CodeCoverage)
 include(CodingStandard)

cmake/Modules/ExternalCMakeProject.cmake

@@ -36,8 +36,13 @@ function(ExternalCMakeProject target url hash basedir cmakedir cmakefile)
     # to a new archive version, compiled objects in an existing build directory appear
     # newer than the updated headers and are not recompiled, which leads to failed
     # links or subtly inconsistent binaries.
-    file(ARCHIVE_EXTRACT INPUT ${CMAKE_BINARY_DIR}/_deps/${archive}
-      DESTINATION ${CMAKE_BINARY_DIR}/_deps/src TOUCH)
+    if(CMAKE_VERSION VERSION_LESS 3.24)
+      file(ARCHIVE_EXTRACT INPUT ${CMAKE_BINARY_DIR}/_deps/${archive}
+        DESTINATION ${CMAKE_BINARY_DIR}/_deps/src)
+    else()
+      file(ARCHIVE_EXTRACT INPUT ${CMAKE_BINARY_DIR}/_deps/${archive}
+        DESTINATION ${CMAKE_BINARY_DIR}/_deps/src TOUCH)
+    endif()
     file(GLOB TARGET_SOURCE "${CMAKE_BINARY_DIR}/_deps/src/${basedir}*")
     list(LENGTH TARGET_SOURCE _num)
     if(_num GREATER 1)

cmake/Modules/Packages/KOKKOS.cmake

@@ -39,8 +39,23 @@ string(TOUPPER ${KOKKOS_LAYOUT} KOKKOS_LAYOUT)
 
 target_compile_definitions(lammps PRIVATE -DLMP_KOKKOS_LAYOUT_${KOKKOS_LAYOUT})
 
+# Use the host random number generator in KOKKOS styles.  This makes runs with
+# the KOKKOS package reproduce the results of the corresponding plain styles,
+# which is required for validating them, but it is slow and not thread safe.
+option(KOKKOS_DEBUG_RNG "Use the host random number generator in KOKKOS styles (for testing only)" OFF)
+mark_as_advanced(KOKKOS_DEBUG_RNG)
+
+if(KOKKOS_DEBUG_RNG)
+  target_compile_definitions(lammps PRIVATE -DLMP_KOKKOS_DEBUG_RNG)
+endif()
+
 message(STATUS "Using " ${KOKKOS_PREC_LOWER} " precision for KOKKOS package")
 message(STATUS "Using " ${KOKKOS_LAYOUT_LOWER} " view layout for KOKKOS package")
+if(KOKKOS_DEBUG_RNG)
+  message(STATUS "Using host random numbers for KOKKOS package")
+else()
+  message(STATUS "Using device random numbers for KOKKOS package")
+endif()
 
 ########################################################################
 # consistency checks and Kokkos options/settings required by LAMMPS
@@ -192,6 +207,7 @@ set(KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/kokkos.cpp
                        ${KOKKOS_PKG_SOURCES_DIR}/npair_kokkos.cpp
                        ${KOKKOS_PKG_SOURCES_DIR}/npair_halffull_kokkos.cpp
                        ${KOKKOS_PKG_SOURCES_DIR}/domain_kokkos.cpp
+                       ${KOKKOS_PKG_SOURCES_DIR}/math_special_kokkos.cpp
                        ${KOKKOS_PKG_SOURCES_DIR}/modify_kokkos.cpp
                        ${KOKKOS_PKG_SOURCES_DIR}/rand_pool_wrap_kokkos.cpp
                        ${KOKKOS_PKG_SOURCES_DIR}/tune_kokkos.cpp

cmake/Modules/StyleHeaderUtils.cmake

@@ -158,6 +158,22 @@ endfunction(GenerateStyleHeaders)
 # one_arg = TRUE selects the creator signature (LAMMPS*); FALSE selects
 # (LAMMPS*,int,char**).  Generated files are accumulated in the global property
 # LAMMPS_STYLE_SOURCES for adding to the lammps target.
+#
+# Each header is walked with a small state machine: 0 = before the
+# "#ifdef XXX_CLASS" marker block, 1 = inside it, 2 = after it.
+#
+# Some style headers wrap the *whole* file, marker block included, in one or
+# more build-configuration guards (a compiler feature test or a library feature
+# macro such as LAMMPS_ZSTD or LMP_HAS_NETCDF), so the class is only defined
+# when that feature is available.  Every conditional directive seen in state 0
+# is collected as such an outer guard and re-emitted around both the #include
+# and the registration calls of that header, so a style whose class definition
+# is compiled out is not registered either.  (By LAMMPS convention the only
+# conditionals allowed before the marker block are such guards; the include
+# guard of the header lives inside the #else branch.)  Inside the marker block
+# (state 1) each XxxStyle(key,Class) marker becomes an explicit add_builtin()
+# call and nested preprocessor directives are copied verbatim so
+# build-config-dependent markers stay guarded.
 function(CreateStyleSource path property style macro base accessor regfunc one_arg includes)
     get_property(files GLOBAL PROPERTY ${property})
 
@@ -169,68 +185,53 @@ function(CreateStyleSource path property style macro base accessor regfunc one_a
     endforeach()
     list(SORT pairs)
 
-    # Some style headers wrap their class definition in a build-configuration
-    # guard (compiler or library feature macro) placed *outside* the
-    # "#ifdef XXX_CLASS" marker block, so the marker parser below cannot see it.
-    # Skip those headers during normal parsing and emit their #include and
-    # registration call by hand, wrapped in the same guard expression.
-    set(special_hdr   "pair_snap_intel.h" "dump_netcdf.h" "dump_netcdf_mpiio.h")
-    set(special_guard "defined(__AVX512F__) && (defined(__INTEL_COMPILER) || defined(__INTEL_LLVM_COMPILER))" "defined(LMP_HAS_NETCDF)" "defined(LMP_HAS_PNETCDF)")
-    set(special_key   "snap/intel" "netcdf" "netcdf/mpiio")
-    set(special_cls   "PairSNAPIntel" "DumpNetCDF" "DumpNetCDFMPIIO")
-
     set(include_block "")
     set(entry_block "")
-    set(present_specials "")
     foreach(entry ${pairs})
         string(REGEX REPLACE "^[^|]*\\|" "" fname "${entry}")
         get_filename_component(bname ${fname} NAME)
-        list(FIND special_hdr "${bname}" spidx)
-        if(NOT spidx EQUAL -1)
-            list(APPEND present_specials ${spidx})
-            set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${fname}")
-            continue()
-        endif()
-        set(include_block "${include_block}#include \"${bname}\"\n")
         set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${fname}")
 
-        # walk the marker block (between "#ifdef XXX_CLASS" and the matching
-        # "#else"/"#endif").  Convert each XxxStyle(key,Class) marker into an
-        # explicit add_builtin() and copy any nested preprocessor directives
-        # verbatim so build-config-dependent markers stay guarded.
         file(STRINGS ${fname} all_lines)
         set(state 0)
         set(depth 0)
+        set(outer_guards "")
+        set(file_entries "")
         foreach(line IN LISTS all_lines)
             if(state EQUAL 0)
                 if("${line}" MATCHES "^#ifdef[ \t]+[A-Z_]+_CLASS")
                     set(state 1)
                     set(depth 1)
+                elseif("${line}" MATCHES "^[ \t]*#[ \t]*if")
+                    string(STRIP "${line}" dline)
+                    list(APPEND outer_guards "${dline}")
+                elseif("${line}" MATCHES "^[ \t]*#[ \t]*endif")
+                    list(POP_BACK outer_guards)
                 endif()
             elseif(state EQUAL 1)
                 if("${line}" MATCHES "^[ \t]*#[ \t]*if")
                     math(EXPR depth "${depth} + 1")
                     string(STRIP "${line}" dline)
-                    set(entry_block "${entry_block}${dline}\n")
+                    set(file_entries "${file_entries}${dline}\n")
                 elseif("${line}" MATCHES "^[ \t]*#[ \t]*elif")
                     if(depth GREATER 1)
                         string(STRIP "${line}" dline)
-                        set(entry_block "${entry_block}${dline}\n")
+                        set(file_entries "${file_entries}${dline}\n")
                     endif()
                 elseif("${line}" MATCHES "^[ \t]*#[ \t]*else")
                     if(depth EQUAL 1)
                         set(state 2)
                     else()
                         string(STRIP "${line}" dline)
-                        set(entry_block "${entry_block}${dline}\n")
+                        set(file_entries "${file_entries}${dline}\n")
                     endif()
                 elseif("${line}" MATCHES "^[ \t]*#[ \t]*endif")
                     math(EXPR depth "${depth} - 1")
                     if(depth EQUAL 0)
                         set(state 2)
                     else()
                         string(STRIP "${line}" dline)
-                        set(entry_block "${entry_block}${dline}\n")
+                        set(file_entries "${file_entries}${dline}\n")
                     endif()
                 elseif("${line}" MATCHES "${macro}\\(([^)]*)\\)")
                     # the style keyword never contains a comma, so split on the
@@ -244,21 +245,24 @@ function(CreateStyleSource path property style macro base accessor regfunc one_a
                         string(SUBSTRING "${inner}" ${after} -1 cls)
                         string(STRIP "${key}" key)
                         string(STRIP "${cls}" cls)
-                        set(entry_block "${entry_block}  ${accessor}().add_builtin(\"${key}\", &creator<${cls}>);\n")
+                        set(file_entries "${file_entries}  ${accessor}().add_builtin(\"${key}\", &creator<${cls}>);\n")
                     endif()
                 endif()
             endif()
         endforeach()
-    endforeach()
 
-    # emit guarded #include + registration for the skipped special-case headers
-    foreach(spidx ${present_specials})
-        list(GET special_hdr ${spidx} shdr)
-        list(GET special_guard ${spidx} sguard)
-        list(GET special_key ${spidx} skey)
-        list(GET special_cls ${spidx} scls)
-        set(include_block "${include_block}#if ${sguard}\n#include \"${shdr}\"\n#endif\n")
-        set(entry_block "${entry_block}#if ${sguard}\n  ${accessor}().add_builtin(\"${skey}\", &creator<${scls}>);\n#endif\n")
+        # wrap the #include and the registration calls of this header in its
+        # outer build-configuration guards (usually none)
+        set(guard_open "")
+        set(guard_close "")
+        foreach(guard IN LISTS outer_guards)
+            set(guard_open "${guard_open}${guard}\n")
+            set(guard_close "${guard_close}#endif\n")
+        endforeach()
+        set(include_block "${include_block}${guard_open}#include \"${bname}\"\n${guard_close}")
+        if(NOT "${file_entries}" STREQUAL "")
+            set(entry_block "${entry_block}${guard_open}${file_entries}${guard_close}")
+        endif()
     endforeach()
 
     set(preamble "#include \"lammps.h\"\n#include \"creator_registry.h\"\n")

cmake/Modules/Tools.cmake

@@ -51,12 +51,28 @@ if(BUILD_LAMMPS_GUI)
   if(NOT BUILD_SHARED_LIBS)
     message(FATAL_ERROR "Building LAMMPS-GUI currently requires setting -D BUILD_SHARED_LIBS=ON")
   endif()
+  # hack to support multi-arch builds for external project
+  if("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
+    list(JOIN CMAKE_OSX_ARCHITECTURES , MACOSX_ARCHS)
+  endif()
+  # hack to encode the LAMMPS build folder into the binary's rpath
+  if(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+    set(LAMMPS_GUI_RPATH "@loader_path")
+  elseif(NOT WIN32)
+    set(LAMMPS_GUI_RPATH "\$ORIGIN")
+  endif()
+  if(LAMMPS_INSTALL_RPATH)
+    list(APPEND LAMMPS_GUI_RPATH ${CMAKE_INSTALL_FULL_LIBDIR})
+  endif()
+  list(JOIN LAMMPS_GUI_RPATH , LAMMPS_GUI_RPATH)
+
   # When building LAMMPS-GUI with LAMMPS we don't support plugin mode and don't include docs.
   ExternalProject_Add(lammps-gui_build
     GIT_REPOSITORY https://github.com/akohlmey/lammps-gui.git
     GIT_TAG main
     GIT_SHALLOW TRUE
     GIT_PROGRESS TRUE
+    LIST_SEPARATOR ,
     CMAKE_ARGS -D BUILD_DOC=OFF
                -D LAMMPS_GUI_USE_PLUGIN=OFF
                -D LAMMPS_SOURCE_DIR=${LAMMPS_SOURCE_DIR}
@@ -67,6 +83,9 @@ if(BUILD_LAMMPS_GUI)
                -D CMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
                -D CMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
                -D CMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
+               -D CMAKE_OSX_ARCHITECTURES=${MACOSX_ARCHS}
+               -D CMAKE_OSX_DEPLOYMENT_TARGET=${CMAKE_OSX_DEPLOYMENT_TARGET}
+               -D CMAKE_INSTALL_RPATH=${LAMMPS_GUI_RPATH}
     DEPENDS lammps
     BUILD_BYPRODUCTS <INSTALL_DIR>/bin/lammps-gui
   )

cmake/packaging/build_linux_tgz.sh

@@ -35,7 +35,7 @@ rm -rf ${DESTDIR}/lib64
 rm -f ${DESTDIR}/lib/ld*.so ${DESTDIR}/lib/ld*.so.[0-9]
 rm -f ${DESTDIR}/lib/lib{c,dl,rt,m,pthread}.so.?
 rm -f ${DESTDIR}/lib/lib{c,dl,rt,m,pthread}-[0-9].[0-9]*.so
-rm -f ${DESTDIR}/lib/libX* ${DESTDIR}/lib/libxcb*
+rm -f ${DESTDIR}/lib/libX* ${DESTDIR}/lib/libxcb* ${DESTDIR}/lib/libxkb*
 rm -f ${DESTDIR}/lib/libgcc_s*
 rm -f ${DESTDIR}/lib/libstdc++*
 echo "Remove oversize potential files"
@@ -70,7 +70,7 @@ do \
 done
 
 echo "Add additional plugins for Qt"
-for dir in styles imageformats
+for dir in styles imageformats tls iconengines
 do \
     cp -r  ${QTDIR}/plugins/${dir} ${DESTDIR}/qtplugins/
     chmod +x ${DESTDIR}/qtplugins/*/*.so

doc/src/Build_extras.rst

@@ -976,6 +976,20 @@ speedup on GPUs for some models, but a slowdown for others. LayoutRight
 is always used for positions on GPUs since it has been found to be
 faster, and when compiling exclusively for CPUs.
 
+.. versionadded:: TBD
+
+The CMake option ``-D KOKKOS_DEBUG_RNG=on`` makes those KOKKOS styles
+that need random numbers (for example :doc:`fix langevin <fix_langevin>`
+or :doc:`fix brownian <fix_brownian>`) use the same random number
+generator as the corresponding plain styles instead of the parallel
+generator of the Kokkos library.  A run on a single MPI process with the
+Serial back end then follows the same trajectory as a run without the
+KOKKOS package, which makes it possible to compare the two directly and
+thus to validate the KOKKOS versions of those styles.  This is a
+validation and debugging aid only: the substitute generator is slower
+and produces the same numbers only when there is no parallelism, so this
+option must not be used for production simulations.
+
 ----------
 
 .. _lepton:

doc/src/Packages.rst

@@ -45,8 +45,8 @@ consistent with the rest of LAMMPS.
 
 The "Examples" column is a subdirectory in the examples directory of the
 distribution which has one or more input scripts that use the package.
-E.g. ``peptide`` refers to the ``examples/peptide`` directory; ``PACKAGES/atc`` refers
-to the ``examples/PACKAGES/atc`` directory.  The "Lib" column indicates``
+E.g. ``peptide`` refers to the ``examples/peptide`` directory; ``PACKAGES/fep`` refers
+to the ``examples/PACKAGES/fep`` directory.  The "Lib" column indicates``
 whether an extra library is needed to build and use the package:
 
 * no  = no library

doc/src/atom_style.rst

@@ -361,7 +361,9 @@ By adding the flag *superellipsoid* to the *ellipsoid* atom_style
 command, the particles can be superellipsoids, which are a
 generalization of ellipsoids with two additional blockiness parameters
 that control the shape.  Superellipsoids also store the principal
-moments of inertia of the particle.
+moments of inertia of the particle.  The *superellipsoid* option is not
+supported by the KOKKOS package version of the *ellipsoid* atom style,
+which will stop with an error message when the option is used.
 
 For the *line* style, particles can be are idealized line segments
 which store a per-particle mass and length and orientation (i.e. the

doc/src/fix_nve_sphere.rst

@@ -99,6 +99,12 @@ be point particles.
 Use of the *disc* keyword is only allowed for 2d simulations, as
 defined by the :doc:`dimension <dimension>` keyword.
 
+.. versionchanged:: TBD
+
+The KOKKOS version of this fix does not support the *dipole/dlm* option of
+the *update* keyword and will stop with an error if it is requested.  Use the
+non-accelerated version of the fix for the DLM integrator.
+
 Related commands
 """"""""""""""""
 

doc/src/kspace_modify.rst

@@ -452,7 +452,9 @@ parameter-selection guidance in the more general dielectric-confined
 setting, see :ref:`(Gao2025) <Gao2025>`. The *auto* setting is
 currently supported by :doc:`kspace_style <kspace_style>` *ewald*, *pppm*,
 *pppm/cg*, *pppm/tip4p*, *pppm/stagger*, and the corresponding
-OpenMP/GPU/Intel variants that reuse the same slab-correction setup.
+OpenMP/GPU/Intel variants that reuse the same slab-correction setup.  The
+KOKKOS variants do not support it and will stop with an error if it is
+requested; use an explicit volfactor with those.
 
 An alternative slab option can be invoked with the *nozforce* keyword
 in lieu of the volfactor.  This turns off all kspace forces in the z

doc/src/pair_brownian.rst

@@ -140,6 +140,15 @@ brownian.
 Only spherical particles are allowed for pair_style brownian/poly.  The
 volume fraction correction is not supported by pair_style brownian/poly.
 
+.. versionchanged:: TBD
+
+The KOKKOS versions of these styles require a half neighbor list and will
+stop with an error if a full neighbor list is requested, as it is by default
+on a GPU.  A full list would visit each pair twice and draw independent
+random numbers each time, so the stochastic part of the pair force would no
+longer be equal and opposite.  Use *package kokkos neigh half* with these
+styles.
+
 These pair styles are only compatible with the following wall fixes:
 :doc:`fix wall/lj93, fix wall/lj126, fix wall/lj1043, fix wall/colloid,
 fix wall/harmonic, fix wall/lepton, fix wall/morse, fix wall/table

doc/src/pair_tersoff.rst

@@ -303,8 +303,11 @@ This pair style requires the :doc:`newton <newton>` setting to be "on"
 for pair interactions.
 
 The *shift* keyword is not supported by the *tersoff/gpu*,
-*tersoff/intel*, *tersoff/kk*, *tersoff/table* or *tersoff/table/omp*
-variants.
+*tersoff/intel*, *tersoff/table* or *tersoff/table/omp* variants.
+
+.. versionchanged:: TBD
+
+   The *shift* keyword is now also supported by the *tersoff/kk* variant.
 
 The *tersoff/intel* pair style is only available when compiling LAMMPS
 with the Intel compilers.

doc/src/pair_tersoff_mod.rst

@@ -204,8 +204,12 @@ This pair style requires the :doc:`newton <newton>` setting to be "on"
 for pair interactions.
 
 The *shift* keyword is not supported by the *tersoff/gpu*,
-*tersoff/intel*, *tersoff/kk*, *tersoff/table* or *tersoff/table/omp*
-variants.
+*tersoff/intel*, *tersoff/table* or *tersoff/table/omp* variants.
+
+.. versionchanged:: TBD
+
+   The *shift* keyword is now also supported by the *tersoff/mod/kk* and
+   *tersoff/mod/c/kk* variants.
 
 The *tersoff/mod* potential files provided with LAMMPS (see the potentials
 directory) are parameterized for metal :doc:`units <units>`.  You can

doc/src/pair_tersoff_zbl.rst

@@ -284,8 +284,13 @@ LAMMPS was built with that package.  See the :doc:`Build package
 This pair style requires the :doc:`newton <newton>` setting to be "on"
 for pair interactions.
 
-The *shift* keyword is currently not supported for the *tersoff/gpu* and
-*tersoff/kk* variants of this pair style.
+The *shift* keyword is currently not supported for the *tersoff/gpu*
+variant of this pair style.
+
+.. versionchanged:: TBD
+
+   The *shift* keyword is now also supported by the *tersoff/zbl/kk*
+   variant.
 
 The tersoff/zbl potential files provided with LAMMPS (see the potentials
 directory) are parameterized for :doc:`"metal" units <units>`.  Also the