Add uenv documentation and LAMMPS + metatomic uenv

CSCS-Alps/uenv.md

@@ -0,0 +1,91 @@
+# uenv
+
+
+Software on Alps is provided via [uenv] (user environments).
+
+## Spack
+
+uenv is based on the [Spack] package manager, 
+therefore all the software in an uenv needs to be available in Spack.
+
+If a software is not available in Spack, you need to create a Spack package for it,
+following the [Spack packaging guide].
+
+## Recipes
+
+A [uenv recipe] is a collection of YAML files describing the uenv (compilers, libraries, applications, etc.).
+An uenv can be built from a recipe using [`stackinator`], or using the [uenv build serivice].
+
+Uenv recipes for the metatensor ecosystem are available under
+
+```
+CSCS-Alps/uenv/
+```
+
+### Updating a package version
+
+To update a package version in an existing recipe, you need to do the following:
+
+1. [Optional] Update the `spack-package` version/commit in the `config.yaml` file,
+2. Update the version of the package in the `environment.yaml` file.
+
+The first step is only required if the version of interest has been added to Spack
+after the version/commit of `spack-packages` specified in the `config.yaml` file.
+
+### Custom Spack packages
+
+Custom Spack packages, overwriting the ones in Spack, can be added to
+
+```
+<PATH_TO_RECIPE>/repo/packages/
+```
+
+## Examples
+
+### Build uenv with build service
+
+Build an uenv from a recipe using the [uenv build serivice]:
+
+```bash
+uenv build <PATH_TO_RECIPE> 
+```
+
+### Build uenv with stackinator
+
+[Install `stackinator`]. 
+Clone the [Alps cluster configuration] repository.
+
+Build an uenv from a recipe using `stackinator`:
+
+```bash
+stack-config --build <PATH_TO_BUILD_DIR> --recipe <PATH_TO_RECIPE> -S <PATH_TO_CLUSTER_CONFIG>
+```
+
+It is recommended to build under `/dev/shm/$USER/`.
+The path to the cluster configuration should point to the correct cluster directory in the `alps-cluster-config` repository.
+
+## Available recipes
+
+### lammps-metatomic
+
+Recipe for building an uenv with LAMMPS and the `metatomic` package.
+The LAMMPS Spack package is a custom package, which uses [metatensor/LAMMPS],
+since the `metatomic` package is not yet available in the official LAMMPS distribution.
+
+The main changes are the following:
+1. Changed `git` attribute to use `metatensor/LAMMPS`
+2. Added `+metatomic` variant to enable `metatomic` (`lammps+metatomic`)
+3. Added dependencies `libmetatensor-torch`, `libmetatomic-torch`, `py-torch` (when `+metatomic`)
+4. Enabled `PKG_ML-METATOMIC` when `+metatomic`, and enforced usage of Spack-installed `metatensor` and `metatomic`
+5. Removed `^[virtuals=mpi] cray-mpich`-specific handling, it's already accounted for in Alps' custom `cray-mpich` package 
+
+The version of PyTorch provided by this uenv is non-distributed.
+
+[uenv]: https://docs.cscs.ch/software/uenv/
+[Spack]: https://spack.readthedocs.io/en/latest/
+[Spack packaging guide]: https://spack.readthedocs.io/en/latest/packaging_guide_creation.html#
+[`stackinator`]: https://eth-cscs.github.io/stackinator/
+[uenv build serivice]: https://docs.cscs.ch/software/uenv/build_service/
+[uenv recipe]: https://eth-cscs.github.io/stackinator/recipes/
+[Install `stackinator`]: https://eth-cscs.github.io/stackinator/#getting-stackinator
+[Alps cluster configuration]: https://github.com/eth-cscs/alps-cluster-config

CSCS-Alps/uenv/lammps-metatomic/compilers.yaml

@@ -0,0 +1,2 @@
+gcc:
+  version: "12"

CSCS-Alps/uenv/lammps-metatomic/config.yaml

@@ -0,0 +1,11 @@
+name: lammps-metatrain
+store: /user-environment
+description: LAMMPS with metatrain software stack support
+spack:
+  repo: https://github.com/spack/spack.git
+  commit: v1.1.1
+  packages:
+    repo: https://github.com/spack/spack-packages.git
+    commit: cd8632aa721261368adfd27e60f789aa9c8288db # PR 3475
+modules: false
+version: 2

CSCS-Alps/uenv/lammps-metatomic/environments.yaml

@@ -0,0 +1,36 @@
+lammps-metatomic:
+  compiler: [gcc]
+  network:
+    mpi: cray-mpich@8.1.32 +cuda
+  unify: true
+  specs:
+  - python@3.12
+  - cmake
+  - ninja
+  - libtool@2.4.6
+  - cuda@12
+  - py-torch@2.8.0 ~distributed ~nccl
+  - kokkos@4.7.01 +wrapper # Has to match the version in LAMMPS
+  - libmetatensor-torch@0.8.4
+  - libmetatomic-torch@0.1.8
+  - plumed +metatomic
+  - lammps@git.2025.9.10.mta2=20250910 +kokkos fft_kokkos=cufft +python +replica +mc +misc +plumed +manifold +metatomic +qtb +reaction +shock +spin +extra-pair +extra-fix
+  variants:
+  - +mpi
+  - +cuda
+  - cuda_arch=90
+  views:
+    develop:
+      link: all
+      # Exclude gcc-runtime to avoid adding a copy of libgomp.so to the view
+      exclude: ["lammps", "gcc-runtime"]
+      uenv:
+        add_compilers: true
+        prefix_paths:
+          LD_LIBRARY_PATH: [lib, lib64]
+    lammps:
+      link: all
+      uenv:
+        add_compilers: true
+        prefix_paths:
+          LD_LIBRARY_PATH: [lib, lib64]

CSCS-Alps/uenv/lammps-metatomic/repo/packages/lammps/660.patch

@@ -0,0 +1,24 @@
+From b46cc6a6a7410108af84a854818c154a17e0ef42 Mon Sep 17 00:00:00 2001
+From: Christoph Junghans <junghans@lanl.gov>
+Date: Fri, 22 Sep 2017 15:17:44 -0600
+Subject: [PATCH] cmake: fix build with system cmake
+
+---
+ cmake/CMakeLists.txt | 4 +++-
+ 1 file changed, 3 insertions(+), 1 deletion(-)
+
+diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
+index bc33da60de..666b77ae3d 100644
+--- a/cmake/CMakeLists.txt
++++ b/cmake/CMakeLists.txt
+@@ -665,7 +665,9 @@ include_directories(${LAMMPS_STYLE_HEADERS_DIR})
+ ############################################
+ add_library(lammps ${LIB_SOURCES})
+ target_link_libraries(lammps ${LAMMPS_LINK_LIBS})
+-add_dependencies(lammps ${LAMMPS_DEPS})
++if(LAMMPS_DEPS)
++  add_dependencies(lammps ${LAMMPS_DEPS})
++endif()
+ set_target_properties(lammps PROPERTIES OUTPUT_NAME lammps${LAMMPS_MACHINE})
+ if(BUILD_SHARED_LIBS)
+   set_target_properties(lammps PROPERTIES SOVERSION ${SOVERSION})

CSCS-Alps/uenv/lammps-metatomic/repo/packages/lammps/Makefile.inc

@@ -0,0 +1,49 @@
+SHELL = /bin/sh
+
+# ---------------------------------------------------------------------
+# build rules and dependencies
+# do not edit this section
+
+include	Makefile.package.settings
+include	Makefile.package
+
+EXTRA_INC = $(LMP_INC) $(PKG_INC) $(MPI_INC) $(FFT_INC) $(JPG_INC) $(PKG_SYSINC)
+EXTRA_PATH = $(PKG_PATH) $(MPI_PATH) $(FFT_PATH) $(JPG_PATH) $(PKG_SYSPATH)
+EXTRA_LIB = $(PKG_LIB) $(MPI_LIB) $(FFT_LIB) $(JPG_LIB) $(PKG_SYSLIB)
+EXTRA_CPP_DEPENDS = $(PKG_CPP_DEPENDS)
+EXTRA_LINK_DEPENDS = $(PKG_LINK_DEPENDS)
+
+# Path to src files
+
+vpath %.cpp ..
+vpath %.h ..
+
+# Link target
+
+$(EXE):	$(OBJ) $(EXTRA_LINK_DEPENDS)
+	$(LINK) $(LINKFLAGS) $(EXTRA_PATH) $(OBJ) $(EXTRA_LIB) $(LIB) -o $(EXE)
+	$(SIZE) $(EXE)
+
+# Library targets
+
+lib:	$(OBJ) $(EXTRA_LINK_DEPENDS)
+	$(ARCHIVE) $(ARFLAGS) $(EXE) $(OBJ)
+
+shlib:	$(OBJ) $(EXTRA_LINK_DEPENDS)
+	$(CC) $(CCFLAGS) $(SHFLAGS) $(SHLIBFLAGS) $(EXTRA_PATH) -o $(EXE) \
+        $(OBJ) $(EXTRA_LIB) $(LIB)
+
+# Compilation rules
+
+%.o:%.cpp
+	$(CC) $(CCFLAGS) $(SHFLAGS) $(EXTRA_INC) -c $<
+
+# Individual dependencies
+
+depend : fastdep.exe $(SRC)
+	@./fastdep.exe $(EXTRA_INC) -- $^ > .depend || exit 1
+
+fastdep.exe: ../DEPEND/fastdep.c
+	cc -O -o $@ $<
+
+sinclude .depend

CSCS-Alps/uenv/lammps-metatomic/repo/packages/lammps/gtest_fix.patch

@@ -0,0 +1,18 @@
+diff --git a/cmake/Modules/GTest.cmake b/cmake/Modules/GTest1.cmake
+index 0c62291..e42137b 100644
+--- a/cmake/Modules/GTest.cmake
++++ b/cmake/Modules/GTest1.cmake
+@@ -7,11 +7,11 @@ else()
+ endif()
+
+ include(ExternalProject)
+-set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
++set(GTEST_URL "https://github.com/google/googletest/archive/release-1.11.0.tar.gz" CACHE STRING "URL for GTest tarball")
+ mark_as_advanced(GTEST_URL)
+ ExternalProject_Add(googletest
+                     URL ${GTEST_URL}
+-                    URL_MD5         ecd1fa65e7de707cd5c00bdac56022cd
++                    URL_MD5         e8a8df240b6938bb6384155d4c37d937
+                     SOURCE_DIR      "${CMAKE_BINARY_DIR}/gtest-src"
+                     BINARY_DIR      "${CMAKE_BINARY_DIR}/gtest-build"
+                     CMAKE_ARGS      ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}

CSCS-Alps/uenv/lammps-metatomic/repo/packages/lammps/hip_cmake.patch

@@ -0,0 +1,58 @@
+From b11049ba1a5fa22ff575f4d4afa6579973425962 Mon Sep 17 00:00:00 2001
+From: Richard Berger <richard.berger@outlook.com>
+Date: Sun, 5 Mar 2023 19:03:38 -0700
+Subject: [PATCH] CMake: Use hip::host and hip::hipcub targets
+
+---
+ cmake/Modules/Packages/GPU.cmake | 13 +++----------
+ 1 file changed, 3 insertions(+), 10 deletions(-)
+
+diff --git a/cmake/Modules/Packages/GPU.cmake b/cmake/Modules/Packages/GPU.cmake
+index 8ac1decc86..21d046606f 100644
+--- a/cmake/Modules/Packages/GPU.cmake
++++ b/cmake/Modules/Packages/GPU.cmake
+@@ -412,7 +412,8 @@ elseif(GPU_API STREQUAL "HIP")
+       set_property(TARGET gpu PROPERTY CXX_STANDARD 14)
+     endif()
+     # add hipCUB
+-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
++    find_package(hipcub REQUIRED)
++    target_link_libraries(gpu PRIVATE hip::hipcub)
+     target_compile_definitions(gpu PRIVATE -DUSE_HIP_DEVICE_SORT)
+
+     if(HIP_PLATFORM STREQUAL "nvcc")
+@@ -461,30 +462,22 @@ elseif(GPU_API STREQUAL "HIP")
+
+   add_executable(hip_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
+   target_compile_definitions(hip_get_devices PRIVATE -DUCL_HIP)
+-  target_link_libraries(hip_get_devices hip::host)
++  target_link_libraries(hip_get_devices PRIVATE hip::host)
+
+   if(HIP_PLATFORM STREQUAL "nvcc")
+     target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_NVCC__)
+-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
+     target_include_directories(gpu PRIVATE ${CUDA_INCLUDE_DIRS})
+     target_link_libraries(gpu PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
+
+     target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_NVCC__)
+-    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/include)
+     target_include_directories(hip_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
+     target_link_libraries(hip_get_devices PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
+   elseif(HIP_PLATFORM STREQUAL "hcc")
+     target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_HCC__)
+-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
+-
+     target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_HCC__)
+-    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
+   elseif(HIP_PLATFORM STREQUAL "amd")
+     target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_AMD__)
+-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
+-
+     target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_AMD__)
+-    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
+   endif()
+
+   target_link_libraries(lammps PRIVATE gpu)
+-- 
+2.39.2
+