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