Skip to main content

Modular potential fitting code for classical MD buckingham potentials

Project description

BuckFit

Prelude

To run the potential fitting code, you must first install LAMMPS and the lammps-cython interface. Installing LAMMPS itself is a relatively easy task. You just download the relevant source files, go to the src directory and run make. Simple. Installing LAMMPS with lammps-cython however is a little more complex.

Here I am going to go through how to install this using make and pip, with the correct dependancies installed using apt (for linux based systems) and brew (for Macs).

This link contains the instructions which most of this guide is based on.

Installing dependencies

As with all great bits of code, you need to install some packages to get things working properly. lammps-cython is no exception. You will need make sure you have openblas, openmpi, and fftw. These can be installed in the follwoing ways.

For Ubuntu/linux systems use:

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

For Mac/OSX systems (using homebrew) use:

brew install openblas open-mpi fftw

(Note: this uses open-mpi in place of mpich, but seems to work).

NOTE: It should also be noted that there are certain libraries that are needed for lamps-python/lammps-cython to run properly. Lammps many still install properly but it will throw up errors later. Common ones to make sure you include are libpng and zlib. Mpich can also be used in place of open-mpi however this is not something I have tested so things may break.

Compiling LAMMPS

Download the version of LAMMPS you want, making sure it is a release from March 23rd 2018. Before this date some of the libraries weren't properly supported. You can either git clone the latest stable version using:

git clone -b stable https://github.com/lammps/lammps.git [path to build location]/lammps

(Or use wget or download the zip and move it to where you want to build LAMMPS.)

Once you have your LAMMPS folder, cd into the src directory (lammps/src/). Before building LAMMPS and creating the shared library, you may want to include some of the LAMMPS packages. This is fairly simple to do and you will probably want to have some of these packages. To see a list of the available packages use make package-status. This will also tell you if they are active or not. To activate any of these packages you can use make yes-<package_name> or to deactivate use make no-<package_name>. If you want to install a bunch of packages in one go you can 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

These are the packages I have installed in my version, though you should note that some packages are not compatible with others and can cause conflicts. So just be careful.

Right, now you are ready to install LAMMPS!

This is done using a make command. Here you can also chose which mode to use, to run as serial or mpi, and which flags to use. I won't pretend to be an expert in this (I am definitely not!), however there are suggested flags to use to get everything working smoothly. The make command I would suggest to use is:

make mode=shlib mpi -j4 LMP_INC="-DLAMMPS_EXCEPTIONS -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64"

Boom! Now you are compiling LAMMPS. Make a cup of tea (or coffee if you prefer) while it runs. This could take about 5 minutes, or longer if you have more packages.

When LAMMPS has finished compiling you will need to copy the .so file to a library directory and all the .h files to an include directory. On the workstations and hpcs, you will not have root permission (i.e. write access to /usr/local/lib and /usr/local/include) so the best place to place these files are in /home/[user]/.local/lib/ and /home/[user]/.local/include/. If these locations don't exist then you can make them. The commands for copying the files over to these directories are:

cp liblammps_mpi.so /home/[user]/.local/lib/liblammps_mpi.so
mkdir /home/[user]/.local/include/lammps/; cp *.h /home/[user]/.local/include/lammps/

NOTE: If you are unsure on the full path of your home directory (i.e. everything before .local) you can type pwd in your home directory and it will give you your path.

Following this you may wish to include the python package to allow a lammps-python environment without installing lammps-cython. To do this, in the src directory, do make install-python. This will only take a second or so to run. If you are installing lammps-cython this step is unnecessary.

Installing lammps-cython

Okay, so if LAMMPS compiled properly, then this should be fairly simple. In practice, this is likely the fiddly bit where everything breaks. Lammps-cython also has some prerequisites. These can easily be installed using:

pip install numpy mpi4py cython

To make sure everything is pointing to the right places, we have a few more steps to go through before installing lammps-cython. Firstly we need to create a .cfg file. This should be placed in ~/.config/lammps-site.cfg, the content of which should be as follows:

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

# 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

NOTE: If a .config directory doesn't exist (i.e. not a writable location), you need to create it. Also if you are installing on a Mac, it doesn't seem to like mpi_cxx, so just use mpi. I.e. mpi_library = mpi.

This file now needs editing to make sure the file paths are correct to where you have placed your .so and .h files. On a similar note, check that the mpi file paths are also correct. These are dependant on your system, or the hpc you are using. Use mpic++ -showme to show a list of the libraries and includes which contain mpi. This will spit out something similar to this:

g++ -I/usr/lib/x86_64-linux-gnu/openmpi/include/openmpi -I/usr/lib/x86_64-linux-gnu/openmpi/include/openmpi/opal/mca/event/libevent2022/libevent -I/usr/lib/x86_64-linux-gnu/openmpi/include/openmpi/opal/mca/event/libevent2022/libevent/include -I/usr/lib/x86_64-linux-gnu/openmpi/include -pthread -L/usr//lib -L/usr/lib/x86_64-linux-gnu/openmpi/lib -lmpi_cxx -lmpi

You will want the file paths which contain openmpi and end in /include and /lib. Ignore the -I/ at the start. This is not needed.

With the config file all setup and pointing to the right locations it should now just be a case of:

pip install lammps-cython

Now is a good time to check that your LD_LIBRARY_PATH is pointing to the correct place. You can check this using echo $LD_LIBRARY_PATH. This should give the file path to where you have saved your .so file, i.e. your lammps_library_dir path in the config file we made earlier. If not you will need to set this using (with your file path):

export LD_LIBRARY_PATH=/home/[user]/.local/lib/

NOTE: This may not stay permanent on workstations or hpcs. To save having to redo this command each time you login add it to your .bash_profile.

Testing

If this works you should be able to run:*

from lammps import Lammps
Lammps()

There are example/test notebooks (basic.ipynb and benchmark.ipynb) located here under Binder Notebooks, which you can use to test everything is running correctly and also give you an idea of how to use lammps-cython.

Debugging a failed compile

LAMMPS itself should compile fine. If this isn't the case, there are suggestions in the LAMMPS manual you can read through. The most likely part of the process that will fail is the installation of lammps-cython. There are a few possible reasons for this, the most likely being clashes in python environments and MPI clashes.

Python environments - If, like myself, you weren't entirely sure what you were doing when you set up your computer/HPC or workstation environment then this could be an issue. The same applies if you have tried to install python through different routes i.e. direct downloads, brew install, anaconda, etc. This can lead to your python paths pointing in different places or being inconsistent. The best way to solve this is to carefully remove the different environments and stick to just one. Personally I would suggest removing all environments and use pyenv. This can be brew/apt installed and allows you to keep all your different python versions and environments in a controlled way. After cleaning up your environments, make sure all your paths are pointing in the right locations and that your .bash_rc, .bash_profile, etc., don't have explicit paths relating to an old environment.

MPI clashes - This one can be a bit of a challenge to fix. Firstly, check the error message you get and see where the paths are pointed. A likely issue is the paths pointing towards mpich when you are using a different compiler, such as openmpi. This is more of an issue on personal computers. To fix this you need to uninstall mpich and remove the files in the path. It would also be wise to remove the cache directories for pip and brew (or equivalent for apt and conda) as the paths can be held in memory. mpi4py should also be removed (including the cache) and reinstalled to make sure the paths are updated. This should hopefully fix the issue. If not, make sure your lammps-site.cfg file contains the right paths.

Also make sure Xcode is up to date. This can also cause issues if not.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

BuckFit-0.0.1.tar.gz (24.6 kB view hashes)

Uploaded Source

Built Distribution

BuckFit-0.0.1-py3-none-any.whl (32.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page