Installation

Installing lammps-cython can be a complex process. But from my experience not too hard on most standard linux distributions. If installation is hard for you I would recommend using the docker images or conda (not done yet) which do not require manual installation of LAMMPS.

Docker

This method should work for Linux, OSX, and windows. The docker image includes the lammps shared library, python3.5, and lammps binary. Everything you need to start experimenting with the package.

docker pull costrouc/lammps-cython

Conda

Right now there are only prebuilt conda packages for linux (python3.5, python3.6). Creating conda packages for OSX is possible and will be done if requested.

Conda is an OS agnostic package manager. It is developed by contiuum analytics. Conda installation is by far the easier way to get started with python and installing complex scientific codes. Once you have conda installed it will be as simple as

conda install -c costrouc -c conda-forge lammps-cython

Pip

Installation via pip requires building the LAMMPS shared library. This is because pypi does not handle binaries in wheels well. Hopefully this changes with manylinux.

Building LAMMPS Shared Library (Linux and OSX)

I will attempt to keep this current on how to install in Ubuntu. Should work similarly for all Linux distributions. I am not knowledgeable on how to install on OSX or Windows (maybe this will change). Before installing lammps make sure that you have all the necessary dependencies. If you are working on a cluster there is a good chance that you will not need to install the dependencies.

Linux Dependencies

For linux derivatives you should have packages very similarly named to the ones below. I have installed on both debian and ubuntu and these packages should work.

apt install build-essential libopenblas-dev libfftw3-dev libopenmpi-dev

OSX Dependecies

Homebrew is the choice of developer for the package manager of OSX. See homebrew installation instructions if you do not already have the package manager. While I have minimal experience using homebrew these instructions should work.

brew install openblas mpich fftw

To install the equivalent of build-essential in linux you will need to have xcode installed. This can be done in the terminal via xcode-select --install. Not sure if necessary and probably already installed on your machine.

Installation

Make sure that your mpi implementation is MPI3. Next download the latest LAMMPS release and untar the download. I would actually recommend using the LAMMPS github repo the archives are smaller, download faster, and are easier to find. Replace <version> with your version you are downloading. wget is used for downloading the archive from the terminal but there are of course other ways.

Attention

The minimum version of LAMMPS required is greater than March 23rd 2018. This is due to several new library methods added.

wget https://github.com/lammps/lammps/archive/<version>.tar.gz
cd lammps-<version>/src

Inside of the lammps directory you will see a directory called src. cd to the src directory. Next make the LAMMPS shared library. Building the shared library should take around 5 minutes without adding on packages. If you need to add packages to LAMMPS this can easily be done. make package-status will list the available packages and if they are activated. You can activate any package by typing make yes-<package>. To deactivate a package type make no-<package>. As an example if you need to use the manybody package this can be installed via make yes-manybody. Note that some of the packages require additional complex dependencies.

To install an near exhaustive list of lammps packages use the following.

export LAMMPS_PACKAGES="asphere body class2 colloid compress coreshell dipole granular kspace manybody mc misc molecule opt peri qeq replica rigid shock snap srd user-reaxc"
for pack in $LAMMPS_PACKAGES; do make "yes-$pack"; done

After you have installed the packages that you would like included in the LAMMPS shared library, compile the source code.

make mode=shlib mpi -j4 LMP_INC="-DLAMMPS_EXCEPTIONS -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64"
cp liblammps_mpi.so /usr/local/lib/liblammps.so
mkdir /usr/local/include/lammps/; cp *.h /usr/local/include/lammps/

Attention

At a minimum the -DLAMMPS_EXCEPTION definition is needed. This is used so that lammps-cython can check if an error in execution has happened and the python package will not compile.

Now all include files has been coppied to /usr/local/include/lammps/ and the shared library has been coppied to /usr/local/lib. This will require root permissions. Another great location that does not require root is $HOME/.local/lib/ and $HOME/.local/include/.

Note

Ensure that the LAMMPS library is installed without any undefined symbols. To check the shared library file run ldd -r liblammps_mpi.so. You should not see any undefined symbols. One reported issue is that the gfortran library is not included by default with LAMMPS when installing additional add-on packages. To fix this issue simply build the LAMMPS library with the gfortran shared library included :commmand:`-lgfortran`.

Installating lammps-cython

lammps-cython installation should be easy if you have exactly followed the steps above. The following step should work.

pip install numpy mpi4py cython
pip install lammps-cython

If it does not you will manually need to specify the location of the lammps and mpi include files. This is similar to the approach that numpy takes. You will need to specify the locations in a file ~/.config/lammps-site.cfg located in the configuration directory. The example input file is included bellow. Change to your needs and then run pip install lammps-cython. It will work if you get the locations correct.

# multiple values can be included seperated by commas
[lammps]
lammps_include_dir = /usr/local/include/lammps/
lammps_library_dir = /usr/local/lib/
# true library filename is liblammps.so notice lib and .so are removed
lammps_library = lammps

# use mpic++ -showme to list libraries and includes
[mpi]
mpi_include_dir = /usr/lib/x86_64-linux-gnu/openmpi/include
mpi_library_dir = /usr/lib/x86_64-linux-gnu/openmpi/lib
# no necissarily needed (default are mpi, mpi_cxx)
mpi_library     = mpi, mpi_cxx

Common Installation Errors

There are some common errors that should be checked before submitting an issue on the github repository.

>>> import lammps
from .core import Lammps

ImportError: liblammps.so: cannot open shared object file: No such file or directory

This error results because python cannot find the LAMMPS library. Meaning that the lammps library is the not in the standard library search path. On a typical linux system these paths are /usr/lib and /usr/local/lib. If you would like to have the LAMMPS library in another directory not in the standard path you must modify the environment variable LD_LIBRARY_PATH.

For any other errors PLEASE add an issue to the github page. I check github often and really want to make this a long-term supported addition to the LAMMPS community!