technical:recipes:lammps

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		 Previous revision
technical:recipes:lammps [2025-11-03 17:23] – created freytechnical:recipes:lammps [2025-11-04 11:49] (current) – frey
Line 8: Line 8:
  
 ====== Where to install ====== ====== Where to install ======
 +
 +As a first step, the appropriate file system location to hold builds of LAMMPS must be chosen.
  
 ===== For the individual ===== ===== For the individual =====
Line 33: Line 35:
  
 <code bash> <code bash>
-[«workgroup»:PROMPT]$ echo $WORKDIR_SW+[PROMPT]$ echo $WORKDIR_SW
 /work/«workgroup»/sw /work/«workgroup»/sw
 </code> </code>
Line 39: Line 41:
 For workgroup software, VALET package definitions should be created in the ''${WORKDIR_SW}/valet'' directory. For workgroup software, VALET package definitions should be created in the ''${WORKDIR_SW}/valet'' directory.
  
 +====== Setup the package directory ======
 +
 +Whichever location was chosen, the LAMMPS software will be located in a subdirectory named ''lammps'' (in this example the home directory will be used).  A directory named ''attic'' is created to hold downloaded source packages:
 +
 +<code bash>
 +[PROMPT]$ LAMMPS_BASEDIR="${HOME}/sw/lammmps"
 +[PROMPT]$ mkdir -p "${LAMMPS_BASEDIR}/attic"
 +</code>
 +
 +Since the goal is to manage distinct versions and variants of LAMMPS, it's best to download source packages from the program's [[https://github.com/lammps/lammps/releases|Github page]].  As of November 2025, the newest stable release is [[https://github.com/lammps/lammps/releases/tag/stable_22Jul2025_update1|update 1 to the 22 July 2025 version]]:
 +
 +<code bash>
 +[PROMPT]$ ( cd "${LAMMPS_BASEDIR}/attic" ; \
 +            curl --remote-name --location \
 +                'https://github.com/lammps/lammps/releases/download/stable_22Jul2025_update1/lammps-src-22Jul2025_update1.tar.gz' \
 +          )
 +[PROMPT]$ ls -l "${LAMMPS_BASEDIR}/attic"
 +total 219083
 +-rw-r--r-- 1 user everyone 226349672 Nov  4 10:08 lammps-src-22Jul2025_update1.tar.gz
 +</code>
 +
 +This means we will use a version identifier of ''22Jul2025.1''.  The remainder of this recipe applies for the first and all subsequent versions and variants of LAMMPS that are built:
 +
 +<code bash>
 +[PROMPT]$ LAMMPS_VERSION="22Jul2025.1"
 +[PROMPT]$ LAMMPS_PREFIX="${LAMMPS_BASEDIR}/${LAMMPS_VERSION}"
 +[PROMPT]$ mkdir -p "$LAMMPS_PREFIX"
 +</code>
 +
 +Finally, unpack the source code in the version's directory and rename it:
 +
 +<code bash>
 +[PROMPT]$ cd "$LAMMPS_PREFIX"
 +[PROMPT]$ tar -xf "${LAMMPS_BASEDIR}/attic/lammps-src-22Jul2025_update1.tar.gz"
 +[PROMPT]$ls
 +lammps-22Jul2025
 +[PROMPT]$ mv lammps-22Jul2025 src
 +</code>
 +
 +====== Build the program ======
 +
 +To build LAMMPS, at the very least a C++ compiler toolchain must be selected.  If the program will be built with MPI parallelism, the compiler should be an MPI C++ compiler wrapper like ''mpicxx''.  In this recipe an Open MPI package atop the Intel oneAPI tools is used on Caviness.
 +
 +<code bash>
 +[PROMPT]$ vpkg_require --context=development openmpi/4.1.4:intel-oneapi-2023
 +Adding dependency `libfabric/1.13.2` to your environment
 +Adding dependency `binutils/2.35` to your environment
 +Adding dependency `gcc/12.1.0` to your environment
 +Adding dependency `intel-oneapi/2023.0.0.25537` to your environment
 +Adding package `openmpi/4.1.4:intel-oneapi-2023` to your environment
 +</code>
 +
 +===== Makefile fragment =====
 +
 +LAMMPS customizes the build environment by means of a Makefile fragment that gets included by the top-level Makefile.  Example fragments can be found in the ''src/MAKE'' subdirectory of the source package:
 +
 +<code bash>
 +[PROMPT]$ cd "${LAMMPS_PREFIX}/src"
 +[PROMPT]$ ls -l src/MAKE
 +total 72
 +drwxr-xr-x 2 user everyone   21 Sep  1 19:29 MACHINES
 +-rw-r--r-- 1 user everyone 3616 Sep  1 19:29 Makefile.mpi
 +-rw-r--r-- 1 user everyone 3605 Sep  1 19:29 Makefile.serial
 +drwxr-xr-x 2 user everyone    2 Sep  1 19:29 MINE
 +drwxr-xr-x 2 user everyone   32 Sep  1 19:29 OPTIONS
 +-rw-r--r-- 1 user everyone 4765 Sep  1 19:29 README
 +</code>
 +
 +Each subdirectory has a purpose:
 +
 +  * **MACHINES**: Makefile fragments for "famous" computing systems and some OS's (like Mac OS X)
 +  * **MINE**: Makefile fragments created by the user/workgroup managing this build
 +  * **OPTIONS**: Makefile fragments for various combinations of compiler suite and parallelism
 +
 +The Intel + OpenMPI fragment at ''src/MAKE/OPTIONS/Makefile.icc_openmpi'' is best-aligned with the choice of compiler in this instance, so a copy will be made:
 +
 +<code bash>
 +[PROMPT]$ cp src/MAKE/OPTIONS/Makefile.icc_openmpi src/MAKE/MINE/Makefile.caviness
 +[PROMPT]$ head -1 src/MAKE/MINE/Makefile.caviness
 +# icc_openmpi = OpenMPI with compiler set to Intel icc
 +</code>
 +
 +The first line of the copy should be modified to match the suffix chosen on the filename (''caviness'') and a description of the toolchain.  Here's what it looks like after being modified:
 +
 +<code bash>
 +[PROMPT]$ head -1 src/MAKE/MINE/Makefile.caviness
 +# caviness = Open MPI compiler atop Intel oneAPI 2023
 +
 +[PROMPT]$ cd src
 +[PROMPT]$ make
 +   :
 +... or one of these from src/MAKE/MINE:
 +
 +# caviness = Open MPI compiler atop Intel oneAPI 2023
 +
 +</code>
 +
 +As it stands the program will build its own BLAS/LAPACK/FFT subroutines -- which are guaranteed to not be optimal.  Since the Intel oneAPI compiler is being used, the Intel MKL can be used for superior numerical performance.  This can be accomplished by merging-in some flags from the ''src/MAKE/OPTIONS/Makefile.oneapi'' fragment:
 +
 +<code>
 +   :
 +#export OMPI_CXX = icc
 +CC =            mpicxx
 +OPTFLAGS =      -xHost -O2 -freciprocal-math
 +CCFLAGS =       -qopenmp-simd -qopenmp -ansi-alias \
 +                -DLMP_INTEL_USELRT -DLMP_USE_MKL_RNG $(OPTFLAGS) \
 +                -I$(MKLROOT)/include
 +   :
 +LINKFLAGS =     -qopenmp-simd -qopenmp $(OPTFLAGS) -L$(MKLROOT)/lib/intel64/
 +LIB =           -ltbbmalloc -lmkl_intel_ilp64 -lmkl_sequential -lmkl_core
 +   :
 +FFT_INC =       -DFFT_MKL -DFFT_SINGLE
 +FFT_PATH =
 +FFT_LIB =
 +   :
 +</code>
 +
 +The environment is now ready for the program to be built.
 +
 +===== Building the program =====
 +
 +With the environment configured, a copy of LAMMPS with default functionality can be build with the ''make'' command:
 +
 +<code bash>
 +[PROMPT]$ cd "${LAMMPS_PREFIX}/src/src"
 +[PROMPT]$ make caviness
 +Gathering installed package information (may take a little while)
 +   :
 +mpicxx -qopenmp-simd -qopenmp -xHost -O2 -ffast-math -freciprocal-math -L/opt/shared/intel-oneapi/2023.0.0.25537/mkl/2023.0.0/lib/intel64/ main.o      -L. -llammps_caviness      -ldl -ltbbmalloc -lmkl_intel_ilp64 -lmkl_sequential -lmkl_core -o ../lmp_caviness
 +size ../lmp_caviness
 +   text    data     bss     dec     hex filename
 +7162653   83576   19352 7265581 6edd2d ../lmp_caviness
 +make[1]: Leaving directory `/home/1001/sw/lammps/22Jul2025.1/src/src/Obj_caviness'
 +</code>
 +
 +If successful, the finished executable will be named ''lmp_«machine»'' where the suffix matches the suffix on the Makefile fragment:
 +
 +<code bash>
 +[PROMPT]$ ls -ld "${LAMMPS_PREFIX}/src/src/"lmp_*
 +-rwxr-xr-x 1 user everyone 84486960 Nov  4 10:52 /home/user/sw/lammps/22Jul2025.1/src/src/lmp_caviness
 +</code>
 +
 +===== Installing the program =====
 +
 +The finished executable should be copied to a ''bin'' directory, mimicking the standard Unix/Linux structuring of directories:
 +
 +<code bash>
 +[PROMPT]$ mkdir "${LAMMPS_PREFIX}/bin"
 +[PROMPT]$ install -C lmp_caviness "${LAMMPS_PREFIX}/bin/lammps"
 +</code>
 +
 +The machine suffix is not retained and the program is renamed as ''lammps''.  Doing this in //every version or variant built// means job scripts can always use the bare command ''lammps'' and VALET can be used to choose which version/variant is in-scope.
 +
 +If, in the future, modifications must be made to this version/variant of LAMMPS, the process of building the new copy //does not inherently destroy the existing executable// that was installed to the ''bin'' directory.
 +
 +<note tip>Once a version/variant of LAMMPS has been built and used for research work, it is generally //not a good idea to modify it//.  In those instances, create a completely new variant/version.</note>
 +
 +===== Activating LAMMPS packages =====
 +
 +Additional LAMMPS functionality exists in //packages// that need to be activated to be compiled into the software.  A list of packages can be displayed:
 +
 +<code bash>
 +[PROMPT]$ cd "${LAMMPS_PREFIX}/src/src"
 +[PROMPT]$ make ps
 +Installed  NO: package ADIOS
 +Installed  NO: package AMOEBA
 +Installed  NO: package APIP
 +Installed  NO: package ASPHERE
 +   :
 +Installed  NO: package VORONOI
 +Installed  NO: package VTK
 +Installed  NO: package YAFF
 +</code>
 +
 +One helpful package is the [[https://docs.lammps.org/Speed_intel.html|INTEL]] package, which contains a variety of optimizations tailored to Intel processors.  On Caviness -- which is built with Intel processors -- the package is enabled prior to ''make'':
 +
 +<code bash>
 +[PROMPT$ $ make yes-INTEL
 +Installing package INTEL
 +
 +[PROMPT]$ make caviness
 +</code>
 +
 +Hybrid parallelism can be enabled by activating the [[https://docs.lammps.org/Speed_omp.html|OPENMP]] package:
 +
 +<code bash>
 +[PROMPT$ $ make yes-OPENMP
 +Installing package OPENMP
 +
 +[PROMPT]$ make caviness
 +</code>
 +
 +====== VALET package definition ======
 +
 +By installing the finished executable in the ''bin'' subdirectory, VALET can automatically find that directory and setup the shell environment accordingly.  A VALET //package definition file// is necessary to facilitate that.
 +
 +<note important>Since this recipe built a copy of LAMMPS in the home directory, the VALET package definition will be created in the user's ''~/.valet'' directory.</note>
 +
 +Information to know before creating the package definition file:
 +
 +  * What was the ''LAMMPS_BASEDIR'' where all versions/variants are located?
 +  * What was the ''LAMMPS_VERSION'' that was built?
 +  * What VALET package(s) were loaded into the environment for the build?
 +
 +In this instance the answers are:
 +
 +  * ''/home/user/sw/lammps''
 +  * ''22Jul2025.1''
 +  * ''openmpi/4.1.4:intel-oneapi-2023''
 +
 +The ''LAMMPS_BASEDIR'' will only be necessary when the definition is first created and //should not change for all subsequent versions/variants build//.
 +
 +The package definition file is written in YAML (YAML Ain't Markup Language):
 +
 +<file yaml lammps.vpkg_yaml>
 +lammps:
 +    prefix: /home/user/sw/lammps
 +    description: Large-scale Atomic/Molecular Massively Parallel Simulator
 +    url: "https://www.lammps.org/"
 +    
 +    default-version: "22Jul2025.1"
 +    
 +    versions:
 +        "22Jul2025.1":
 +            description: Open MPI 4.1.4, Intel oneAPI 2023, MKL
 +            dependencies:
 +                - openmpi/4.1.4:intel-oneapi-2023
 +</file>
 +
 +With the VALET package definition created, it can be queried e.g.
 +
 +<code bash>
 +[PROMPT]$ vpkg_versions lammps
 +
 +Available versions in package (* = default version):
 +
 +[/home/user/.valet/lammps.vpkg_yaml]
 +lammps         Large-scale Atomic/Molecular Massively Parallel Simulator
 +* 22Jul2025.1  Open MPI 4.1.4, Intel oneAPI 2023, MKL
 +
 +   :
 +</code>
 +
 +===== Using LAMMPS in jobs =====
 +
 +With the VALET package definition present, jobs can make use of LAMMPS by adding the appropriate version/variant:
 +
 +<code bash>
 +vpkg_require lammps/22Jul2025.1
 +</code>
  • technical/recipes/lammps.1762208587.txt.gz
  • Last modified: 2025-11-03 17:23
  • by frey