Making LAMMPS usable within Python and vice versa requires putting the
LAMMPS Python module file (lammps.py) into a location where the
Python interpreter can find it and installing the LAMMPS shared library
into a folder that the dynamic loader searches or into the same folder
where the lammps.py file is. There are multiple ways to achieve
this.
Build the LAMMPS executable and library with
-DBUILD_SHARED_LIBS=on, -DLAMMPS_EXCEPTIONS=on and
-DPKG_PYTHON=on (The first option is required, the other two
are optional by recommended). The exact file name of the shared
library depends on the platform (Unix/Linux, MacOS, Windows) and
the build configuration being used. The installation base folder
is already set by default to the $HOME/.local directory, but
it can be changed to a custom location defined by the
CMAKE_INSTALL_PREFIX CMake variable. This uses a folder
called build to store files generated during compilation.
# create build folder
mkdir build
cd build
# configure LAMMPS compilation
cmake -C cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
# compile LAMMPS
cmake --build .
# install LAMMPS into $HOME/.local
cmake --install .
This leads to an installation to the following locations:
File |
Location |
Notes |
|---|
LAMMPS Python Module |
|
X.Y depends on the installed Python version
|
LAMMPS shared library |
|
|
LAMMPS executable |
|
|
LAMMPS potential files |
|
Set LAMMPS_POTENTIALS environment variable to this path |
For a system-wide installation you need to set
CMAKE_INSTALL_PREFIX to a system folder like /usr (or
/usr/local). The installation step (not the
configuration/compilation) needs to be done with superuser
privilege, e.g. by using sudo cmake --install .. The
installation folders will then by changed to:
File |
Location |
Notes |
|---|
LAMMPS Python Module |
|
X.Y depends on the installed Python version
|
LAMMPS shared library |
/usr/lib/ (32bit)
/usr/lib64/ (64bit)
|
|
LAMMPS executable |
|
|
LAMMPS potential files |
|
|
To be able to use the “user” installation you have to ensure that
the folder containing the LAMMPS shared library is either included
in a path searched by the shared linker (e.g. like
/usr/lib64/) or part of the LD_LIBRARY_PATH environment
variable (or DYLD_LIBRARY_PATH on MacOS). Otherwise you will
get an error when trying to create a LAMMPS object through the
Python module.
# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# MacOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
If you plan to use the LAMMPS executable (e.g., lmp), you may
also need to adjust the PATH environment variable (but many
newer Linux distributions already have $HOME/.local/bin
included). Example:
export PATH=$HOME/.local/bin:$PATH
To make those changes permanent, you can add the commands to your
$HOME/.bashrc file. For a system-wide installation is is not
necessary due to files installed in system folders that are loaded
automatically when a login shell is started.
Compile LAMMPS with either CMake or the
traditional make procedure in shared
mode. After compilation has finished type (in the
compilation folder):
This will try to install (only) the shared library and the python
module into a system folder and if that fails (due to missing
write permissions) will instead do the installation to a user
folder under $HOME/.local. For a system-wide installation you
would have to gain superuser privilege, e.g. though sudo
File |
Location |
Notes |
|---|
LAMMPS Python Module |
|
X.Y depends on the installed Python version
|
LAMMPS shared library |
|
X.Y depends on the installed Python version
|
For a system-wide installation those folders would then become.
File |
Location |
Notes |
|---|
LAMMPS Python Module |
|
X.Y depends on the installed Python version
|
LAMMPS shared library |
|
X.Y depends on the installed Python version
|
No environment variables need to be set for those, as those
folders are searched by default by Python or the LAMMPS Python
module.
For the traditional make process you can override the python
version to version x.y when calling make with
PYTHON=pythonX.Y. For a CMake based compilation this choice
has to be made during the CMake configuration step.
If the default settings of make install-python are not what you want,
you can invoke install.py from the python directory manually as
$ python install.py -m <python module> -l <shared library> -v <version.h file> [-d <pydir>]
The -m flag points to the lammps.py python module file to be installed,
the -l flag points to the LAMMPS shared library file to be installed,
the -v flag points to the version.h file in the LAMMPS source
and the optional -d flag to a custom (legacy) installation folder
If you use a legacy installation folder, you will need to set your
PYTHONPATH and LD_LIBRARY_PATH (and/or DYLD_LIBRARY_PATH) environment
variables accordingly as explained in the description for “In place use”.
A virtual environment is a minimal Python installation inside of a
folder. It allows isolating and customizing a Python environment
that is mostly independent from a user or system installation.
For the core Python environment, it uses symbolic links to the
system installation and thus it can be set up quickly and will not
take up much disk space. This gives you the flexibility to
install (newer/different) versions of Python packages that would
potentially conflict with already installed system packages. It
also does not requite any superuser privileges. See PEP 405:
Python Virtual Environments for more
information.
To create a virtual environment in the folder $HOME/myenv,
use the venv module as follows.
# create virtual environment in folder $HOME/myenv
python3 -m venv $HOME/myenv
For Python versions prior 3.3 you can use virtualenv command instead of “python3 -m venv”. This
step has to be done only once.
To activate the virtual environment type:
source $HOME/myenv/bin/activate
This has to be done every time you log in or open a new terminal
window and after you turn off the virtual environment with the
deactivate command.
When using CMake to build LAMMPS, you need to set
CMAKE_INSTALL_PREFIX to the value of the $VIRTUAL_ENV
environment variable during the configuration step. For the
traditional make procedure, not additional steps are needed.
After compiling LAMMPS you can do a “Python module only”
installation with make install-python and the LAMMPS Python
module and the shared library file are installed into the
following locations:
File |
Location |
Notes |
|---|
LAMMPS Python Module |
|
X.Y depends on the installed Python version
|
LAMMPS shared library |
|
X.Y depends on the installed Python version
|
If you do a full installation (CMake only) with “install”, this
leads to the following installation locations:
File |
Location |
Notes |
|---|
LAMMPS Python Module |
|
X.Y depends on the installed Python version
|
LAMMPS shared library |
|
|
LAMMPS executable |
|
|
LAMMPS potential files |
|
|
In that case you need to modify the $HOME/myenv/bin/activate
script in a similar fashion you need to update your
$HOME/.bashrc file to include the shared library and
executable locations in LD_LIBRARY_PATH (or
DYLD_LIBRARY_PATH on MacOS) and PATH, respectively.
For example with:
# Unix/Linux
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
# MacOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
You can also compile LAMMPS as usual in
“shared” mode leave the shared library and Python
module files inside the source/compilation folders. Instead of
copying the files where they can be found, you need to set the environment
variables PYTHONPATH (for the Python module) and
LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on MacOS
For Bourne shells (bash, ksh and similar) the commands are:
export PYTHONPATH=${PYTHONPATH}:${HOME}/lammps/python
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/lammps/src
For the C-shells like csh or tcsh the commands are:
setenv PYTHONPATH ${PYTHONPATH}:${HOME}/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
On MacOS you may also need to set DYLD_LIBRARY_PATH accordingly.
You can make those changes permanent by editing your $HOME/.bashrc
or $HOME/.login files, respectively.
To verify if LAMMPS can be successfully started from Python, start the
Python interpreter, load the lammps Python module and create a
LAMMPS instance. This should not generate an error message and produce
output similar to the following: