2. Installation

This page documents how to properly install LAMMPS and FitSNAP. First we begin with how to install LAMMPS specifically for FitSNAP.

  • If you do not want to manually install LAMMPS, please see Minimal conda install, but note this version of conda LAMMPS does not included recent features like neural networks or ACE descriptors.

  • If you want a quick summary of installation instructions, see Quick Installation.

2.1. LAMMPS Installation

Since LAMMPS is the backbone of FitSNAP, we begin with instructions on how to install LAMMPS specifically for using FitSNAP. The following few sections cover basics of installing LAMMPS with Python library support.

2.1.1. MPI for LAMMPS and FitSNAP

Both LAMMPS and FitSNAP are parallelized for optimal performance.

We build MPI from source using OpenMPI version 4.1.4 (https://www.open-mpi.org/) and the instructions at https://www.open-mpi.org/faq/?category=building#easy-build.

After building, add your openmpi executable path to your PATH variable as well so that LAMMPS can automatically find your MPI install, e.g.:

# in e.g., ~/.bashrc
MPI_DIR=/usr/local/openmpi
export PATH=$MPI_DIR/bin:$PATH

2.1.2. Python dependencies

We recommend creating a virtual environment with python -m venv or conda. After creating your virtual environment, make sure it is activated for all future steps, e.g.:

conda create --name fitsnap python=3.10
conda activate fitsnap

Now install the necessary pre-requisites to build Python-LAMMPS using pip or conda:

python -m pip install numpy scipy scikit-learn virtualenv psutil pandas tabulate mpi4py Cython
# For nonlinear fitting:
python -m pip install torch
# For fitting ACE:
python -m pip install sympy pyyaml
# For contributing to docs:
python -m pip install sphinx sphinx_rtd_theme sphinxcontrib-napoleon

To make sure MPI is working, make a Python script called test.py with the following:

from mpi4py import MPI
comm = MPI.COMM_WORLD
print("Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()))

And see the output of running test.py in parallel:

# NOTE: the line order is not deterministic
$ mpirun -np 4 python test.py
Proc 0 out of 4 procs
Proc 1 out of 4 procs
Proc 2 out of 4 procs
Proc 3 out of 4 procs

2.1.3. LAMMPS for FitSNAP

First clone the LAMMPS repo:

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

This creates a lammps directory, where we will build LAMMPS using cmake` and make:

cd /path/to/lammps
mkdir build-fitsnap
cd build-fitsnap
# Use cmake to build the Makefile
cmake ../cmake -DLAMMPS_EXCEPTIONS=yes \
              -DBUILD_SHARED_LIBS=yes \
              -DMLIAP_ENABLE_PYTHON=yes \
              -DPKG_PYTHON=yes \
              -DPKG_ML-SNAP=yes \
              -DPKG_ML-IAP=yes \
              -DPKG_ML-PACE=yes \
              -DPKG_SPIN=yes \
              -DPYTHON_EXECUTABLE:FILEPATH=`which python`
# Build a LAMMPS executable and shared library
make
# Install Python-LAMMPS interface
make install-python

Do not be alarmed by runtime library warnings after cmake, or -Weffc++ and -Wunused-result warnings during make. This will create a LAMMPS executable lmp, which should be used to run MD using FitSNAP fits. This will also create a Python-LAMMPS interface located in your Python site-packages/lammps directory. Set the following environment variables so that your Python can find the LAMMPS library:

LAMMPS_DIR=/path/to/lammps
# For MacOS, use DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$LAMMPS_DIR/build-fitsnap:$LD_LIBRARY_PATH

Also make sure your Python-LAMMPS interface is working by doing the following in your Python interpreter:

import lammps
lmp = lammps.lammps()

which should produce no errors.

After completing this LAMMPS installation, please see Install FitSNAP with latest LAMMPS to use FitSNAP.

2.1.4. LAMMPS PACE install

Computes for ACE descriptors are currently in our modified LAMMPS repo (https://github.com/jmgoff/lammps_compute_PACE), so the installation instructions are a little different if you want to use ACE.

  1. Clone our modified LAMMPS repo and set up a typical LAMMPS build:

    git clone -b compute-pace https://github.com/jmgoff/lammps_compute_PACE
cd lammps_compute_PACE
mkdir build && cd build

  2. Set up a typical LAMMPS build the ML-PACE library enabled:

    cmake ../cmake -DLAMMPS_EXCEPTIONS=yes \
               -DBUILD_SHARED_LIBS=yes \
               -DMLIAP_ENABLE_PYTHON=yes \
               -DPKG_PYTHON=yes \
               -DPKG_ML-SNAP=yes \
               -DPKG_ML-IAP=yes \
               -DPKG_ML-PACE=yes \
               -DPKG_SPIN=yes \
               -DPYTHON_EXECUTABLE:FILEPATH=`which python`

  3. Download the modified lammps-user-pace code that contains extra arrays for breaking out descriptor contributions:

    git clone https://github.com/jmgoff/lammps-user-pace-1
cp lammps-user-pace-1/ML-PACE/ace-evaluator/ace_evaluator.* ./lammps-user-pace-v.2022.10.15/ML-PACE/ace-evaluator/
make -j
make install-python

  4. Now, set up paths:

    # Use DYLD_LIBRARY_PATH if using MacOS, on Linux use LD_LIBRARY_PATH:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lammps_compute_PACE/build

  5. Now we can get and use FitSNAP:

    cd /path/to/where/you/want/FitSNAP
git clone https://github.com/FitSNAP/FitSNAP
# Set python path so you can run FitSNAP as executable:
export PYTHONPATH=$PYTHONPATH:/path/to/where/you/want/FitSNAP

Note for infrequent installation issues: For some versions of OMP, the LAMMPS/PYTHON interface may produce errors when running, leading to a LAMMPS exception that kills FitSNAP jobs. If your install completes successfully and you have problems with the execution of examples in the example folder, try recompiling lammps with these alternative D flags.

  1. Alternative D flags for python/omp errors:

    cmake ../cmake -D LAMMPS_EXCEPTIONS=on \
               -D PKG_PYTHON=on \
               -D BUILD_SHARED_LIBS=on \
               -D CMAKE_BUILD_TYPE=Debug \
               -D PKG_ML-IAP=on \
               -D PKG_ML-PACE=on \
               -D PKG_ML-SNAP=on \
               -D BUILD_MPI=on \
               -D BUILD_OMP=off \
               -D CMAKE_INSTALL_PREFIX=<$HOME>/.local \
               -D PKG_MOLECULE=on

With key changes coming from turning off omp.

For a summary/review of all these steps, see see Quick Installation.

2.2. FitSNAP Installation

There are two primary ways to get started with FitSNAP: (1) building LAMMPS manually, and (2) a simple conda environment using the packaged LAMMPS that ships with conda. The former option allows for more recent LAMMPS features.

2.2.1. Install FitSNAP with latest LAMMPS

Both FitSNAP and LAMMPS have been optimized to work with MPI. For optimal performance of both, we recommend building and configuring your favored flavor of MPI before continuing (see LAMMPS Installation docs).

  1. Set up environment and build LAMMPS (see LAMMPS Installation docs)

  2. Clone the FitSNAP repository:

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

  3. Add the cloned repository path to your PYTHONPATH environment variable:

    FITSNAP_DIR=\path\to\FitSNAP
export PYTHONPATH=$FITSNAP_DIR:$PYTHONPATH

  4. You should now be able to run the FitSNAP examples in FitSNAP/examples.

  5. For a summary/review of all these steps, see see Quick Installation.

2.2.2. Minimal conda install

  • WARNING: Conda lammps installation does NOT include ACE descriptor set, SPIN package, or new LAMMPS settings needed for fitting neural networks. If you want to use these newer settings, please build LAMMPS from source as explained in the LAMMPS Installation docs.

A minimal working environment can be set up using the Python distribution package Anaconda (https://www.anaconda.com).

After installing Anaconda:

  1. Add conda-forge to your Conda install, if not already added:

    conda config --add channels conda-forge

  2. Create a new Conda environment:

    conda create -n fitsnap python=3.10
conda activate fitsnap

  3. Install dependencies:

    conda install lammps
python -m pip install numpy scipy scikit-learn virtualenv psutil pandas tabulate mpi4py Cython

  4. Clone the FitSNAP repository:

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

  5. Add the cloned repository path to your PYTHONPATH environment variable, e.g. in ~/.bashrc or ~/.bash_profile:

    FITSNAP_DIR=\path\to\FitSNAP
export PYTHONPATH=$FITSNAP_DIR:$LAMMPS_DIR/python:$PYTHONPATH

  • TIP: Periodically use the command git pull in the cloned directory for updates