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.
.. code-block:: bash
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
.. code-block:: bash
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.
.. code-block:: bash
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.
.. code-block:: bash
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
```` 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.
.. code-block:: bash
wget https://github.com/lammps/lammps/archive/.tar.gz
cd lammps-/src
Inside of the lammps directory you will see a directory called
**src**. :command:`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-``. To deactivate a package type
``make no-``. 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.
.. code-block:: bash
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.
.. code-block:: bash
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 :command:`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.
.. code-block:: bash
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.
.. code-block:: ini
# 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.
.. code-block:: python
>>> 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
:command:`/usr/lib` and :command:`/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
:command:`LD_LIBRARY_PATH`.
For any other errors PLEASE add an `issue to the gitlab page
`_. I check gitlab often
and really want to make this a long-term supported addition to the
LAMMPS community!