Skip to content

Latest commit

 

History

History
150 lines (117 loc) · 4.9 KB

README.md

File metadata and controls

150 lines (117 loc) · 4.9 KB
Raw

All issues and contributions should be done on Gitlab. Github is used only as a mirror for visibility

lammps-cython

A high-performance cython wrapper around LAMMPS. Lammps is a great molecular dynamics package that has an unmatched set of potentials and fixes. This package offers unique features such as minimizing I/O by allowing direct access to thermostats and atom properties and allowing interactive lammps within python interpreters such a ipython. The goal of this project is to put an opinionated wrapper around LAMMPS (the good parts) and allow the user to easily extend it's functionality in python. The api should feel very similar to HOOMD and is being actively developed.

Latest Release latest release
latest release
Package Status status
License license
Build Status gitlab pipeline status
Binder Notebooks binder notebooks

Documentation

Full documentation can be found at lammps-cython.

Features

  • Full MPI support
  • Pythonic API inspired by HOOMD
  • Supports Python 2 and 3
  • Heavily documented and tested
  • Elimination of unnecessary file I/O for thermostats and atoms properties

A neat feature of the wrapper is that lammps can be run regularly using the following script (use "-i" instead of stdin). This is the command pylammps when the package is installed.

from lammps import Lammps
import sys
Lammps(args=sys.args)

Installation

lammps-cython has several options for installation. The easiest way is using the provided docker containter image costrouc/lammps-cython or conda install.There is no plan to support pip wheels. Other methods require manual installation of lammps. Detailed installation are provieded in the documentation. If you have any issues with installation be submit an issue at the gitlab repository.

  • conda: conda install -c costrouc -c conda-forge lammps-cython
  • docker: docker pull costrouc/lammps-cython:latest

Otherwise the general path to installation is install LAMMPS as a shared library then edit ~/.config/lammps-site.cfg to include the paths of necissary libraries. See example below.

[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

Then pip install lammps-cython should just work.

Conda Image

The conda image is built only for linux and python versions (3.5, 3.6). There is no plan to support Windows due to MPI being a dependency. However, if OSX is needed please raise an issue.

conda install -c costrouc -c conda-forge lammps-cython

Docker Image

The docker image costrouc/lammps-cython uses python3.5 and has the library preinstalled with the executables pylammps and lammps available.

Tutorials

Work is being done to show how to use the features of lammps-cython for now just visit the tutorial page.

These will turn to links when the tutorial exists.

  • basic usage
  • modify atom positions
  • get forces and velocity for each atom and compute potential energy

Contributing

All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome! These should be submitted at the Gitlab repository. Github is only used for visibility.

Contributors:

License

MIT