Appendix A: Building LAMMPS with CMake

In this appendix, we will give a brief tutorial on how to build LAMMPS with CMake. Unlike the traditional Makefile, CMake can detect available hardware, tools, features, and libraries and adjust the LAMMPS default build configuration accordingly. CMake allows customized settings with a text mode or graphical user interface, without requiring any knowledge of file formats or complex command-line syntax. In addition, CMake can automate dependency tracking for all files and configuration options.

Technical requirements

To execute the instructions in this chapter, you need a platform to compile LAMMPS (for example, a Linux Terminal).

Prerequisites for working with LAMMPS

Before we start working with LAMMPS, we need to get a few things up and running for hassle-free execution:

• Downloading the source code
• Installing dependencies
• Downloading MPICH

We'll look at the preceding points in the following sections.

Downloading the source code

You can download the LAMMPS source code from GitHub by entering the following command in the terminal:

git clone https://github.com/lammps/lammps.git

If, instead, the source code is downloaded from other sources (for example, the LAMMPS download page at https://lammps.sandia.gov/download.html), please make sure to unzip accordingly.

Installing the dependencies

The following commands will install the necessary components (use sudo before each apt command if required):

apt install build-essential

apt install cmake

apt install gfortran    

apt update

apt upgrade

As the preceding components are being installed, progress will be displayed on the terminal screen. As for the Fast Fourier Transform package, if there is no third-party package detected on the machine, CMake will use the embedded KISS FFT library by default.

Downloading MPICH

To enable parallel computation of LAMMPS and communication among the cores and nodes, a framework or Message Passing Interface (MPI) is needed. MPICH is a high performance and widely portable implementation of the MPI standard. The required source code can be downloaded directly from the terminal by entering this:

sudo apt install mpich

Alternatively, the source code can be downloaded using the instructions provided on the official site (www.mpich.org) and has to be decompressed and built:

tar -zxvf mpich3.tar.gz

./configure –enable-shared=yes

In the preceding command, the --enable-shared=yes option is necessary to build a library. The final command is to complete the make:

make && make install

Once MPICH has been installed, LAMMPS can be built with parallel processing capabilities. Otherwise, LAMMPS can only be built to process in serial with a single processor.

Building LAMMPS

When building LAMMPS, an additional folder should be set up to temporarily store configuration files. In LAMMPS, CMake supports out-of-source compilation, and multiple configurations containing different choices of LAMMPS packages, settings, or compilers can be created in other folders outside the source.

In the folder where the LAMMPS source code has been downloaded and unzipped, enter the following command to access the relevant folder:

cd lammps

Then, a new build folder can be created to store different configurations:

mkdir build

This folder can then be accessed with the following command:

cd build

Once accessed, the rest of the installation process can be continued inside it.

Including packages in the build

When building LAMMPS, the source code in the src folder is automatically selected for compilation. The optional packages can be included or excluded as required. The selected packages will influence the compilation time and the size of the executable, and in general, there is no need to include a package if you do not plan to use its features. In the lammps/cmake/presets folder, CMake provides a list of pre-configuration files that are used in common simulation scenarios.

The following screenshot shows the preset file, minimal.cmake, which activates a few commonly used packages for fast compilation:

Figure 12.1 – minimal.cmake located in lammps/cmake/presets

As you can see, on line 4, an ALL_PACKAGES variable is created that contains four packages (KSPACE, MANYBODY, MOLECULE, and RIGID). In lines 6 to 8, the packages are iteratively activated via a loop. More packages can be included by adding to the set command.

Other preset files activate other combinations of packages, such as most.cmake, as shown in the next screenshot:

Figure 12.2 – most.cmake located in lammps/cmake/presets

As you can see, this file lists a longer collection of packages to activate (line 5). Other preset files include all_on.cmake, which activates all existing packages, and all_off.cmake, which deactivates all existing packages to reset.

The required preset file can be called when compiling LAMMPS, as will be explained later in this section.

Including modified codes

CMake automatically builds the source code files that start with pair_, fix_, compute_, and so on. When compiling, custom-written source code files will be automatically included if they are preceded by these terms. If not, the filenames have to be added to the appropriate style header file in the src folder. The full list of automatically detected terms is available in StyleHeaderUtils.cmake, located in the lammps/cmake/modules/ folder.

Building with CMake

By default, CMake automatically selects a compiler based on internal preferences and it will add optimization flags as appropriate. Here is a list of advanced flags that are empty by default and can be modified by the user before compilation:

• Global compiler options (set value to yes or no):

  -D CMAKE_TUNE_FLAGS=value

• Name of the C++ compiler:

  -D CMAKE_CXX_COMPILER=name            

• Name of the C compiler:

  -D CMAKE_C_COMPILER=name              

• Name of the Fortran compiler:

  -D CMAKE_Fortran_COMPILER=name        

• Flags to use with the C++ compiler:

  -D CMAKE_CXX_FLAGS=string             

• Flags to use with the C compiler:

  -D CMAKE_C_FLAGS=string               

• Flags to use with the Fortran compiler:

  -D CMAKE_Fortran_FLAGS=string         

• Add an executable file to a path via the make install command:

  -D CMAKE_INSTALL_PREFIX=path               

• Control compilation options (set value to Release or Debug):

  -D CMAKE_BUILD_TYPE=value                 

• Set the name of the executable file:

  -D LAMMPS_MACHINE=string         

More information about CMake flags can be found in the LAMMPS manual (https://lammps.sandia.gov/doc/Howto_cmake.html).

As an example, the following command installs the packages in the minimal.cmake preset file and prepares a compiled executable file called lmp_test:

cmake -C ../cmake/presets/minimal.cmake -D LAMMPS_MACHINE=test -D CMAKE_BUILD_TYPE=Debug ../cmake

A summary of build configurations is provided on the screen, as shown in the following screenshot:

Figure 12.3 – The build configuration

As you can see, if the settings displayed are satisfactory, the build can be commenced with the make command:

make

The preceding step creates the executable file that can be used to run LAMMPS scripts. Every time a modification is made to the source code, cleaning via the make clean command followed by recompilation are required to create a new executable that registers the modification.

Important Note:

It should be noted that depending on machine configurations (for example, standalone or HPC clusters) and/or the operating system used, the preceding steps may not compile LAMMPS properly. In such cases, it is advisable to web search for specific solutions or to contact the appropriate support staff.

This section describes a LAMMPS compilation in a Linux environment. In the next section, we will describe a LAMMPS compilation in Windows.

Compiling LAMMPS in Windows

This section was contributed by Abdullah Arafat, an apprentice of Dr. Shafat Mubin, and a senior year undergraduate student of Materials Science and Engineering at Khulna University of Engineering and Technology (KUET) in Bangladesh. He is experienced in molecular modelling and molecular dynamics simulations, with proficiency in Python, LAMMPS, VESTA, and Materials Studio. He is keenly interested in computational physics and materials science and is currently engaged in his undergraduate thesis on the growth kinetics of 2D materials.

In this section, the procedure to build LAMMPS in Windows using CMake is detailed. Before beginning, please make sure to update Windows to its latest version.

First, the source code needs to be downloaded and CMake for Windows needs to be installed. The source code can be downloaded using Git for Windows, as described next.

Downloading Git for Windows

You can download Git from the link: https://git-scm.com/downloads.

Once downloaded and installed, Git for Windows can be used to download the LAMMPS source code as described in the next section.

Downloading the source code

You can download the LAMMPS source code from GitHub with the following command in Windows Command Prompt or PowerShell:

git clone https://github.com/lammps/lammps.git

Alternatively, you can download the zipped file from the official LAMMPS GitHub repository: https://github.com/lammps/lammps.

The following screenshot shows the downloaded .zip file from the aforementioned link:

Figure 12.4 – The downloaded .zip file from the LAMMPS GitHub repository

Unzip the zipped file, lammps-master.zip, in your desired directory, which we will refer to as LAMMPS_DIR in the following instructions.

Next, we outline the installation of CMake for Windows.

Downloading CMake for Windows

You can download CMake for Windows from the following link: https://cmake.org/download

Download the installer suitable for your platform and install it, as shown in the following screenshot:

Figure 12.5 – Multiple installers of CMake

Once completed, you will have access to the source code and CMake for Windows. The instructions in the following section will describe the installation of MPI to facilitate parallel processing and Codeblocks to provide an Integrated Development Environment (IDE).

Downloading Microsoft MPI

You can download MS-MPI from the following link: https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi.

Important Note:

Please note that MS-MPI is only required if you want to run LAMMPS on multiple parallel processes (similar to MPICH).

The following screenshot shows the downloadable versions available:

Figure 12.6 – The latest version of MS-MPI

Download both msmpisetup.exe and msmpisdk.msi, and install them.

Downloading Code::Blocks

You can download Codeblocks with MinGW (for example, codeblocks-20.03mingw-setup.exe) from the following link: http://www.codeblocks.org/downloads/binaries

MinGW refers to Minimalist GNU for Windows, so installing Codeblocks with MinGW will include the GCC/G++/GFortran compiler and the GDB debugger, which will allow you to build LAMMPS with more convenience.

Having completed the preceding prerequisite installations, we move on to building LAMMPS using these tools.

Developing LAMMPS

We follow these steps to start building LAMMPS:

1. In the folder where the LAMMPS source code has been downloaded and unzipped (which we will call LAMMPS_DIR), create a new folder and rename it build.
2. Now run CMake(cmake-gui), enter LAMMPS_DIR/cmake in the box titled Where is the source code, enter LAMMPS_DIR/build in the box underneath titled Where to build the binaries, and click Configure.
3. When configuring the project for the first time, a new window will appear asking for the generator to use for this project, where the CodeBlocks – MinGW Makefiles option can be selected. Click Finish, as shown in the following screenshot:
   

   Figure 12.7 – Using cmake-gui to configure LAMMPS for the first time

   In the preceding screenshot, the folder that contains the source code (that is, LAMMPS_DIR) for this particular example is the I:/lammps folder entered in the two boxes at the top.

4. Now select the desired LAMMPS packages to include in the LAMMPS executable to be built, as seen in the following screenshot:
   

   Figure 12.8 – cmake-gui after selecting the required packages and clicking Configure and Generate

   As you can see, packages can be selected by checking their corresponding boxes under the Value column. However, some packages may require additional steps, for example, BUILD_DOC, PKG_KOKKOS, and PKG_LATTE, for which the LAMMPS manual (https://lammps.sandia.gov/doc/Build_extras.html) should be consulted.

   Tip:

   For a minimal installation, the default selection of packages can be used.

5. After generating with CMake, a Codeblocks project called lammps.cbp will be created. Open this project with Codeblocks and press Ctrl + F9, or click the Build button, as marked in the following screenshot:

Figure 12.9 – Code::Blocks after successfully compiling LAMMPS

As demonstrated, after successful compilation you may notice the message Process terminated with status 0 and 0 error(s) in the Build log at the bottom. Concurrently, an executable file titled lmp.exe is generated in the build directory of the LAMMPS folder, LAMMPS_DIR.

This executable can be used to run a LAMMPS script from Command Prompt. Also, you can add the location of lmp.exe in the user or system path variable to access it from anywhere in the system. To set LAMMPS as a user path variable, open Command Prompt, and type the following:

setx PATH "LAMMPS_DIRuild;%PATH%"

To set LAMMPS as a system path variable, open Command Prompt as administrator, and type this:

setx /m PATH "LAMMPS_DIRuild;%PATH%"

As described earlier, LAMMPS_DIR entered in both the aforementioned Command Prompt lines should refer to the folder containing the source code.

To verify that LAMMPS has been properly built, select an existing LAMMPS input script to test run, for example, the in.crack script located in examples/crack/ in the LAMMPS folder. Open Command Prompt or PowerShell to navigate to this directory and enter either of the followings commands:

• For serial execution, use this:

  lmp -in in.crack

• For parallel execution (using mpi with 2 cores), use the following:

  mpiexec -n 2 lmp -in in.crack

Successful execution of the in.crack script produces a screenshot similar to the following:

Figure 12.10 – Command Prompt after successfully executing in.crack

In this section, we learned about the LAMMPS compilation process in Windows. While Windows offers its own set of conveniences, it does not facilitate other features. Please see this webpage (https://lammps.sandia.gov/doc/Build_windows.html) from the LAMMPS manual for a brief overview of building LAMMPS in Windows.

Apart from using CMake, LAMMPS can be built using traditional Make, which offers a quicker way to compile and is discussed in the next section.

Building with Make

Make is a traditional method to build LAMMPS that uses a configuration file, called a makefile, to specify build options. The LAMMPS optional packages need to be included manually in this method.

First, you should change your directory to the source code folder:

cd src

Before compilation, each desired package should be included using the make yes-<package> command, where <package> is the name of the selected package. For example, you would use this if you wanted to include the MOLECULE package:

make yes-molecule

This operation copies all the files in src/MOLECULE to the src folder and prepares them for compilation.

In order to build LAMMPS, a customized Makefile.<machine> file is required based on the system used, where <machine> represents the type of machine setup being used (for example, serial or mpi).

The src/MAKE folder contains these customized files, the OPTIONS folder contains specific options that can be enabled, the MACHINES folder stores configurations for specific machines, and MINE usually stores your customized makefiles.

If we need to change some flags, such as for the integer data size, we open a certain makefile (for example, Makefile.serial or Makefile.mpi) in the src/MAKE folder, find the LMP_INC line, and add the required –D flags:

LMP_INC  =  -DLAMMPS_GZIP  _DLAMMPS_SMALLBIG

The complete list of flags can be found on the appropriate page of the LAMMPS manual (https://lammps.sandia.gov/doc/Build_settings.html).

After completing the previous steps, we can type make <machine> -jN to compile the code, where <machine> corresponds to the same text as in Makefile.<machine>. For example, entering make mpi will use Makefile.mpi as the configuration file. Additionally, the –jN flag can be used to specify the number of cores used to compile:

make mpi –j4

When LAMMPS is built for the first time, it assembles a list of dependencies. When LAMMPS is rebuilt, recompilation is necessary. If settings in the makefile are changed, then all existing objects must be deleted using the make clean-<machine> command, as here:

make clean–all

It should be noted that if this traditional Make is used in the LAMMPS source directory, CMake will generate an error if this is attempted in the same directory. In such a case, the make no-all purge command has to be used to uninstall and delete existing files before CMake can proceed.

Further reading

Build LAMMPS with CMake: https://lammps.sandia.gov/doc/Build_cmake.html

Build LAMMPS with Make: https://lammps.sandia.gov/doc/Build_make.html