2. Install LAMMPS

This page describes how to obtain the source code for this fork and set up the environment before building. Unlike the upstream LAMMPS distribution, this repository is not available through package managers or conda; it must be cloned directly from the project Git repository and compiled from source.

2.1. Prerequisites¶

The following software must be available on your system before building:

2.2. Clone the repository¶

Clone the repository into your working directory using Git:

# Clone over HTTPS
git clone https://github.com/YOUR_ORG/lammps-customfork.git

# Or over SSH
git clone git@github.com:YOUR_ORG/lammps-customfork.git

cd lammps-customfork

The repository follows a branching strategy aligned with upstream LAMMPS. The main branch tracks the latest stable upstream release with this fork's patches applied on top.

2.3. Module setup (HPC)¶

On HPC clusters using the module environment system, load the following modules before configuring and building. The exact module names vary by cluster; adjust to match your system's available modules.

# Example for a typical HPC cluster (adjust module names as needed)
module purge
module load gcc/11.2.0
module load openmpi/4.1.1
module load cmake/3.22.1
module load fftw/3.3.10

# Verify the environment
which mpicc
cmake --version

A reproducible environment file is provided at env/modules.sh in the repository root. You can source it directly:

source env/modules.sh

3. Build LAMMPS

This fork uses CMake exclusively for its build system. A make-based build is not supported. The procedure follows the standard LAMMPS CMake build workflow with additional flags for the packages required by this fork.

3.1. Build with CMake¶

Create a build directory outside the source tree, configure with CMake, then compile. The -DCMAKE_BUILD_TYPE=Release flag enables full compiler optimizations.

# From the repository root
mkdir build && cd build

cmake ../cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_COMPILER=mpicxx \
  -DPKG_BPM=yes \
  -DPKG_MOLECULE=yes \
  -DPKG_MISC=yes \
  -DPKG_KSPACE=yes \
  -DFFT=FFTW3 \
  -DFFTW3_LIBRARY=/path/to/fftw/lib/libfftw3.a \
  -DFFTW3_INCLUDE_DIR=/path/to/fftw/include

# Build using all available cores
make -j$(nproc)

If the build succeeds, the executable will be located at build/lmp. You can optionally install it to a system path:

make install   # installs to CMAKE_INSTALL_PREFIX (default: /usr/local)

3.2. Required packages¶

The following packages are required for the simulation workflows supported by this fork. They must be enabled at configure time.

3.3. Optional packages¶

The following packages are optional but recommended for extended functionality. They can be enabled by adding the corresponding flag to the CMake command.

3.4. HPC cluster build¶

A ready-made build script is provided at env/build_hpc.sh in the repository. It loads the required modules, creates a clean build directory, configures with the standard flag set, and compiles. Review and edit the module names at the top of the script before running.

cat env/build_hpc.sh   # review first
bash env/build_hpc.sh  # then run

4. Run LAMMPS

4.1. Basic usage¶

Once the executable lmp is built, run LAMMPS by passing an input script with the -in flag:

# Serial run
./lmp -in in.script

# Parallel run with MPI (4 processors)
mpirun -np 4 ./lmp -in in.script

# Redirect log output to a file
mpirun -np 4 ./lmp -in in.script -log run.log

Command-line options relevant to this fork:

-in <file>

Path to the LAMMPS input script.

-log <file>

Write log output to the specified file instead of log.lammps.

-screen none

Suppress all output to screen (useful in batch jobs).

-var <name> <value>

Pass a variable from the command line into the input script.

4.2. Example input scripts¶

Several example input scripts are provided in the examples/ directory of the repository. Each subdirectory contains a README file describing the simulation system and expected output.

4.3. Batch submission (Slurm)¶

A template Slurm batch script is provided at env/submit.sh. A minimal example is shown below:

#!/bin/bash
#SBATCH --job-name=lammps-run
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=16
#SBATCH --time=04:00:00
#SBATCH --output=slurm-%j.out

source env/modules.sh

mpirun -np $SLURM_NTASKS ./build/lmp \
  -in examples/polymer_network/in.network \
  -log run.log \
  -screen none

5. Custom packages

This section describes the packages enabled in this fork, with notes on any behavior that differs from the upstream LAMMPS documentation. Packages listed here with no modification notes behave identically to their upstream counterparts.

5.1. PKG_BPM — Bonded Particle Model¶

The BPM package provides bond styles and fixes designed for bonded particle model simulations, including breakable bonds suited to fracture mechanics studies. This fork uses BPM as the primary bonding framework for polymer network simulations.

Relevant bond styles

• bond_style bpm/spring — harmonic spring bond with a stretch-based failure criterion
• bond_style bpm/rotational — spring bond with rotational stiffness

Minimal input script example

bond_style      bpm/spring
bond_coeff      1  1000.0  1.5  0.0  1
fix             1 all nve/bpm/sphere
fix             2 all wall/gran/region …

5.2. PKG_MOLECULE¶

The MOLECULE package adds pair, bond, angle, dihedral, and improper styles for modeling molecular systems. It is required for any simulation using explicit topology (bonds, angles, dihedrals) defined in the data file.

5.3. PKG_MISC¶

The MISC package includes several miscellaneous fix and compute styles that do not fit into other packages. In this fork, several computes from MISC are used in post-processing to extract per-bond stretch distributions.

6. Errors & troubleshooting

This page covers the most common errors encountered when building or running this fork, along with their solutions. For errors not listed here, consult the upstream LAMMPS errors page and the repository issue tracker.

Build errors¶

CMake cannot find FFTW3

If CMake reports "Could not find FFTW3", verify that the FFTW3_LIBRARY and FFTW3_INCLUDE_DIR paths are set correctly on the CMake command line. On HPC clusters, the FFTW module must be loaded before running CMake.

# Check that the library file exists at the path you specified
ls /path/to/fftw/lib/libfftw3.a

Undefined symbols for PKG_BPM

If the linker reports undefined symbols related to BPM classes, confirm that -DPKG_BPM=yes was included in your CMake configure command. Run cmake -L build/ | grep BPM to verify the flag is set.

Runtime errors¶

Illegal bond in BPM simulation

The message "Bond atom missing in fix nve/bpm/sphere" typically indicates that atom communication cutoffs are too small. Increase comm_modify cutoff in your input script:

comm_modify mode single cutoff 3.0

Fix nve/bpm/sphere requires atom style sphere

This fix requires that particles have radius and angular velocity degrees of freedom. Ensure your input script includes:

atom_style sphere

Command reference

This section provides an index of fix, compute, pair, and bond styles available in this build. Styles added or modified relative to upstream LAMMPS are marked CUSTOM.

For the full upstream command reference, see docs.lammps.org/commands_list.html.

Fix styles

Compute styles