Skip to content

A user-friendly Python package to manipulate input and output files of LAMMPS molecular dynamics code. One Python class per LAMMPS file type. Include conversion into pandas DataFrame.

License

Notifications You must be signed in to change notification settings

kkempfer/easylammps

Repository files navigation

EasyLAMMPS

A user-friendly Python package to manipulate input and output files of Large-scale Atomic/Molecular Massively Parallel Simulator LAMMPS molecular dynamics code. One Python class per LAMMPS file type. Include conversion into pandas.DataFrame objects.

Installation

Create and activate a virtual Python environment (recommended) with the name easylammps, for example using Anaconda package and environment manager :

conda create --name easylammps
conda activate easylammps

Clone this repository :

git clone https://github.com/kkempfer/easylammps.git

Install easylammps and its dependencies :

cd easylammps
pip install .

Dependencies

Required :

  • networkx Data structures for graphs and graph algorithms
  • numpy N-dimensional array
  • pandas Labeled data analysis

Recommended :

Build the documentation (optional)

Enter to the documentation directory :

cd docs

Create and activate the virtual Python environment easylammps-dev based on the environment-dev.yml file :

conda env create -f environment-dev.yml
conda activate easylammps-dev

Make the documentation using sphinx :

make html

Deactivate your virtual Python environment :

conda deactivate

Access the documentation in the easylammps/docs/build/html directory.

Install LAMMPS as a shared library with Python (optional)

Coupling Python with LAMMPS opens the door to many advanced extensions. Fortunately, the lammps Python library already wraps the LAMMPS C-library interface. Here, we propose a quick installation guide.

Clone the official LAMMPS repository (stable release) :

git clone https://github.com/lammps/lammps.git
cd lammps
git checkout stable
git pull

Use the virtual Python environment where easylammps is installed (recommended) :

conda activate easylammps

Prepare the building directory and run cmake with at least these options (replace pythonX.Y by your python version) :

mkdir build-python
cd build-python
cmake -D BUILD_SHARED_LIBS=ON \
      -D LAMMPS_EXCEPTIONS=ON \
      -D PKG_PYTHON=ON \
      -D CMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
      -D PYTHON_EXECUTABLE=$CONDA_PREFIX/bin/python \
      -D PYTHON_INCLUDE_DIR=$CONDA_PREFIX/include/pythonX.Y \
      -D PYTHON_LIBRARY=$CONDA_PREFIX/lib/libpythonX.Y.so \
      ../cmake

More options to add in cmake are available here. Among them, some useful ones are presented here :

      -D LAMMPS_MACHINE=python # Suffix to append to lmp binary
      -D PKG_MOLECULE=ON # Model molecular systems with fixed covalent bonds
      -D PKG_RIGID=ON    # Rigid constraints on collections of atoms or particles
      -D PKG_KSPACE=ON   # Long-range electrostatic interaction

Once ready, build and install LAMMPS as a shared library with Python :

make
make install

Finally, we need to add the library path which contains the installed liblammps.so to LD_LIBRARY_PATH, but only when our virtual Python environment easylammps is active. Anaconda provides a way to manage environment variables. The procedure is given below.

Enter to the conda environment directory and create these subdirectories and files :

cd $CONDA_PREFIX
mkdir -p ./etc/conda/activate.d
mkdir -p ./etc/conda/deactivate.d
touch ./etc/conda/activate.d/env_vars.sh
touch ./etc/conda/deactivate.d/env_vars.sh

Edit ./etc/conda/activate.d/env_vars.sh as follows :

#!/bin/sh

export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"

Edit ./etc/conda/deactivate.d/env_vars.sh as follows :

#!/bin/sh

# The first, third and fourth lines are there to arrange for
# every component of the search path to be surrounded by `:`,
# to avoid special-casing the first and last component. The
# second line removes the specified component.

LD_LIBRARY_PATH=:$LD_LIBRARY_PATH:
LD_LIBRARY_PATH=${LD_LIBRARY_PATH//:$CONDA_PREFIX\/lib:/:}
LD_LIBRARY_PATH=${LD_LIBRARY_PATH#:}
LD_LIBRARY_PATH=${LD_LIBRARY_PATH%:}

You should now be able to run LAMMPS from the command line and to import lammps module within Python :

lmp_python
python -c "import lammps"

Do not forget to deactivate your virtual Python environment when you are done working :

conda deactivate

NOTE

For now, installing LAMMPS as a shared library with Python is not mandatory to use the easylammps package. In future, we may add some functionalities using the lammps Python library.


Examples

Coming soon !

Developments

  • Use of flake8 linter and flake8-docstrings extension to check Python code syntax
  • Use of black to auto-format Python code
  • Use of pytest for testing
  • Use of sphinx to auto-build documentation based on Python docstrings
  • Add InputTools object to read LAMMPS input file ?
  • Add RestartTools object to read LAMMPS restart file ?

License

EasyLAMMPS is licensed under the GNU Affero General Public License v3 license. See the LICENSE file for a full description.

Acknowledgements

I kindly thank Julien Devémy who introduced me to the Python programming language. Part of the code used to write easylammps as been taken and modified from his lammps-tools package.

I gratefully acknowledge Alain Dequidt for his inspiring ideas in scientific computing.

Get in touch

Please send bug reports, ideas and questions on GitHub.

About

A user-friendly Python package to manipulate input and output files of LAMMPS molecular dynamics code. One Python class per LAMMPS file type. Include conversion into pandas DataFrame.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages