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!