Compiling
Quick start instructions using pre-compiled binaries can be found in the section here.
Compiling the source codes may require downloading and installing a few dependent packages. To ensure compatibility, we also list the versions that were used during development and testing.
Package Dependence
LAMMPS mesoscale and molecular dynamics software https://lammps.org/ (version, Aug 2, 2023)
tinyxml2 package for parsing XML https://github.com/leethomason/tinyxml2 (version 9.0.0)
libtorch (PyTorch C++ API) https://pytorch.org/cppdocs/ (version 2.0.0)
liblapacke (Numerical linear algebra) https://netlib.org/lapack/ (version 3.10.0)
libfftw3 (FFT package) https://www.fftw.org/ (version 3.3.8)
libmpi (Open MPI package) https://www.open-mpi.org/ (version 11.4.0)
For lammps you may also need the lastest versions of libpng
and libjpeg
and
other packages (depending on the options you choose for compilation), see
lammps documentation for details.
Scripts and Makefiles have been put together to help with compilation within
lammps. This may require further reading of the lammps compilation steps and
editing the makefiles to adjust the source and library installation locations.
We have put together prototype makefiles and scripts for both serial
and
mpi
builds.
Compiling mlmod-lammps involves the following steps:
Download
lammps
from https://lammps.org/, pytorchlibtorch
from http://pytorch.org/, and install the other dependencies. All themlmod
scripts also can be downloaded from the mlmod_github.Copy
mlmod
files into the lammps distribution at location$lammps_dir
. The$lammps_dir
gives the base directory for lammps./src
,./lib
. We put together an automated script copy_src_to_lammps.sh (also available from mlmod_github/src). This is run by specifying the lammps directory:./copy_src_to_lammps.sh -l $lammps_dir
To install instead manually the
mlmod
files, copy the mlmod./lib
directory to the lammps./lib/mlmod
directory. Copy the mlmod./src/USER-MLMOD
directory to the lammps./src
directory. Copy the mlmod./src/USER-MLMOD/MAKE
to the lammps./src/MAKE/MINE
directory. Copy any other needed makefiles to corresponding locations.You may need to adjust paths and settings in makefiles. For example, for
libtorch
, we use directory naming conventions for chosen CXX11 ABIslibtorch_cxx11
orlibtorch_no_cxx11
. The Makefiles are located in$lammps_dir/lib/mlmod/MAKE
,$lammps_dir/lib/vtk
, and$lammps_dir/src/MAKE/MINE
.Activate the
mlmod
and related packages in lammps by:cd $lammps_dir/src make yes-user-mlmod yes-molecule yes-vtk
Build using scripts
Build the mlmod shared library
libmlmod.so
by going to the lammps./lib/mlmod
directory and running./build_mlmod_serial.sh
or./build_mlmod_mpi.sh.
You may need to adjust the makefiles for your system’s dependencies for the locations of the installed libraries and include files. We will discuss below primarily theserial
version, but thempi
build proceeds similarly.Build the main executable
lmp_mlmod_serial
by:cd $lammps_dir/src ./build_mlmod_lammps.sh
You may need to adjust the makefiles.
You can test the build by calling:
echo "info system" >& test.in && lmp_mlmod_serial -in test.in
Given shared library dependencies, you may need to adjust the
LD_LIBRARY_PATH
. For example:export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$lammps_dir:$lammps_dir/../lib/mlmod:$lammps_dir/../lib/mlmod/libtorch_cxx11/lib
Build manually
While the scripts above automate some of the build process, the makfiles also can be used more directly for
serial
andmpi
compilation. We give the manual steps for building the package, which might be helpful in trouble-shooting or for other target environments.Be sure to activate the mlmod package in lammps:
cd $lammps_dir/src make yes-user-mlmod yes-molecule yes-vtk
For
mpi
builds, you may need to adjust the makefiles to point to the libraries for your system configuration. Forserial
builds, compile the MPI stubs by going into lammps$lammps_dir/src/STUBS
and runningmake
. You may need to adjust theABI_CXX11
interface used for consistency on your system.Build the
mlmod
library by:cd $lammps_dir/lib/mlmod make -f ./MAKE/Makefile.lib.mlmod_serial lib_shared
This should result in the shared library
libmlmod.so
. Similarly you can use./MAKE/Makefile.lib.mlmod_mpi
for building anmpi
version of the library.Copy the lammps related makefile information into place for
mlmod
with:cd $lammps_dir/lib/mlmod cp ./MAKE/Makefile.lammps.mlmod_serial Makefile.lammps
Or similarly, copy
./MAKE/Makefile.lammps.mlmod_mpi
formpi
builds.Copy the lammps related makefile information into place for
vtk
with:cd $lammps_dir/lib/vtk cp Makefile.lammps.mlmod_serial Makefile.lammps
Or similarly, copy
./MAKE/Makefile.lammps.mlmod_mpi
formpi
builds.Build the main executable
lmp_mlmod_serial
using:cd $lammps_dir/src make mlmod_serial
Similarly,
make mlmod_mpi
formpi
builds. You may need to adjust the makefiles for your particular platform.You can test the build by calling:
echo "info system" >& test.in && lmp_mlmod_serial -in test.in
For
mpi
builds be sure to usempirun
when testing and running simulations:echo "info system" >& test.in && mpirun -n 4 lmp_mlmod_mpi -in test.in
Given shared library dependencies, you may need to adjust the
LD_LIBRARY_PATH
. For example:export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$lammps_dir:$lammps_dir/../lib/mlmod:$lammps_dir/../lib/mlmod/libtorch_cxx11/lib
How to use the package is discussed briefly here.
Unit Tests for the mlmod
package can be found in the $mlmod_git/tests
folder. Tests are performed with the scripts ./run_test.sh
and uses the pytest
package.
Examples: For further details on setting up models and running simulations, see the examples folder and mlmod website.
Additional Information
For more details, see the lammps documentation pages https://lammps.org/ and http://atzberger.org/.
For installation of pre-compiled binaries, see the quick start instructions.