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 setuptools
# For nonlinear (neural network) 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 sphinx_tabs sphinxcontrib-bibtex sphinxcontrib-youtube myst_parser

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 -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.

Note

There is no longer a need to use modified versions of LAMMPS or PACE libraries for ACE model fitting. The compute pace used by FitSNAP to calculate ACE descriptors has been fully integrated into the ML-PACE package as of the August 29, 2024 LAMMPS stable release (https://github.com/lammps/lammps/tree/stable). The most recent development version can be found in the default branch of the public LAMMPS repository (https://github.com/lammps/lammps).

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