jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update Python installation docs

This commit is contained in:
Axel Kohlmeyer 2020-10-06 12:15:56 -04:00
parent 5d08f629ab
commit 1afd9b1c83
No known key found for this signature in database
GPG Key ID: D9B44E93BF0C375A
2 changed files with 308 additions and 371 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

678
doc/src/Python_install.rst
View File

@ -1,21 +1,22 @@
Installation Installation
************ ************
The LAMMPS Python module enables calling the :ref:`LAMMPS C library API <lammps_c_api>` The LAMMPS Python module enables calling the :ref:`LAMMPS C library API
from Python by dynamically loading functions in the LAMMPS shared library through the <lammps_c_api>` from Python by dynamically loading functions in the
Python ``ctypes`` module. Because of the dynamic loading, it is required that LAMMPS shared library through the Python `ctypes <ctypes_>`_
LAMMPS is compiled in :ref:`"shared" mode <exe>`. It is also recommended module. Because of the dynamic loading, it is required that LAMMPS is
to compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled. compiled in :ref:`"shared" mode <exe>`. It is also recommended to
compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled.
Two files are necessary for Python to be able to invoke LAMMPS code: Two files are necessary for Python to be able to invoke LAMMPS code:
* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder * The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
* The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or ``liblammps.dll``) * The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or
from the folder where you compiled LAMMPS. ``liblammps.dll``) from the folder where you compiled LAMMPS.
.. _ctypes: https://docs.python.org/3/library/ctypes.html
.. _python_virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment .. _python_virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
.. _python_venv: https://docs.python.org/3.8/library/venv.html .. _python_venv: https://docs.python.org/3/library/venv.html
.. _python_pep405: https://www.python.org/dev/peps/pep-0405 .. _python_pep405: https://www.python.org/dev/peps/pep-0405
.. _python_install_guides: .. _python_install_guides:
@ -23,27 +24,60 @@ Two files are necessary for Python to be able to invoke LAMMPS code:
Installing the LAMMPS Python Module and Shared Library Installing the LAMMPS Python Module and Shared Library
====================================================== ======================================================
Making LAMMPS usable within Python and vice versa requires putting the LAMMPS Making LAMMPS usable within Python and vice versa requires putting the
Python module into a location that the Python interpreter can find and LAMMPS Python module file (``lammps.py``) into a location where the
installing the LAMMPS shared library into a folder that the dynamic loader Python interpreter can find it and installing the LAMMPS shared library
searches. For some potentials LAMMPS also needs to know where it can find the into a folder that the dynamic loader searches or into the same folder
necessary potential files. where the ``lammps.py`` file is. There are multiple ways to achieve
this.
Both CMake and traditional make build options offer ways to automate these tasks. #. Install both files into a Python ``site-packages`` folder, either
system-wide or in the corresponding user-specific folder. This way no
additional environment variables need to be set, but the shared
library is otherwise not accessible.
#. Do a full LAMMPS installation of libraries, executables, selected
headers, documentation (if enabled), and supporting files (only
available via CMake), which can also be either system-wide or into
user specific folders.
#. Do an installation into a virtual environment. This can either be
an installation of the python module only or a full installation.
#. Leave the files where they are in the source/development tree and
adjust some environment variables.
.. tabs:: .. tabs::
.. tab:: CMake (local user) .. tab:: Full install (CMake-only)
LAMMPS can be configured and compiled as shared library with CMake by enabling the ``BUILD_SHARED_LIBS`` option. :ref:`Build the LAMMPS executable and library <library>` with
The file name of the shared library depends on the platform (Unix/Linux, MacOS, Windows) and the build configuration ``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
being used. See :ref:`Build the LAMMPS executable and library <library>` for more details and how the name of the ``-DPKG_PYTHON=on`` (The first option is required, the other two
shared library and executable is determined. 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.
Make certain this folder is empty or does not exist if you do not
want to inherit any settings from a previous compilation attempt.
After compilation, the generated executables, shared library, Python module, .. code-block:: bash
and other files can be installed to a custom location defined by the
``CMAKE_INSTALL_PREFIX`` setting. By default, this is set to the current # configure LAMMPS compilation
user's ``$HOME/.local`` directory. This leads to an installation to the following locations: cmake -B build -C cmake/presets/minimal.cmake \
-D BUILD_SHARED_LIBS=on -D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on cmake
# compile LAMMPS
cmake --build build
# install LAMMPS into $HOME/.local
cmake --install build
This leads to an installation to the following locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes | | File | Location | Notes |
@ -54,96 +88,17 @@ Both CMake and traditional make build options offer ways to automate these tasks
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | | | LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | |
| | * ``$HOME/.local/lib64/`` (64bit) | | | | * ``$HOME/.local/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | ``$HOME/.local/bin/`` | | | LAMMPS executable | * ``$HOME/.local/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | ``$HOME/.local/share/lammps/potentials/`` | | | LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
The following is a minimal working example: For a system-wide installation you need to set
``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
1. Install LAMMPS Shared Library and Python module using CMake ``/usr/local``). The installation step (**not** the
configuration/compilation) needs to be done with superuser
.. code-block:: bash privilege, e.g. by using ``sudo cmake --install build``. The
installation folders will then by changed to:
# create and change into build directory
mkdir build
cd build
# configure LAMMPS compilation
# compile with shared library, PYTHON package, and C++ exceptions
# TODO: add more options to customize your LAMMPS installation
cmake -C ../cmake/presets/minimal.cmake \
-D BUILD_SHARED_LIBS=on \
-D PKG_PYTHON=on \
-D LAMMPS_EXCEPTIONS=on \
../cmake
# compile LAMMPS (in parallel for faster builds)
cmake --build . --parallel
# install LAMMPS into $HOME/.local
cmake --install .
2. Configure Environment Variables
To use this installation you have to ensure that the folder containing
the LAMMPS shared library is part of the ``LD_LIBRARY_PATH`` environment variable (or
``DYLD_LIBRARY_PATH`` on MacOS). This allows the dynamic library loader of your system
to find the LAMMPS shared library when needed.
.. code-block:: bash
# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# MacOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
LAMMPS will also need to know the location of the folder
containing its potential files. This can be set with the ``LAMMPS_POTENTIALS``
environment variable:
.. code-block:: bash
export LAMMPS_POTENTIALS=$HOME/.local/share/lammps/potentials
If you are planning to also use the LAMMPS executable (e.g., ``lmp``), also set the ``PATH`` variable:
.. code-block:: bash
export PATH=$HOME/.local/bin:$PATH
To set these environment variables for each new shell, add the above
``export`` commands at the end of the ``$HOME/.bashrc`` file.
3. Verify if LAMMPS can be successfully started from Python
.. code-block:: bash
$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import lammps
>>> lmp = lammps.lammps()
LAMMPS (18 Sep 2020)
using 1 OpenMP thread(s) per MPI task
>>>
.. note::
If you recompile LAMMPS, you will have to also rerun the install step to
ensure the latest Python module and shared library are installed.
.. tab:: CMake (system-wide)
A system-wide installation allows all users to run Python with LAMMPS
included. Note that during the installation step you will need to either be
root or use ``sudo`` to elevate your write privileges. The compilation steps are identical
to the local user installation, with the only difference that
``CMAKE_INSTALL_PREFIX`` is set to system folder such as ``/usr``. This leads to
the following installation locations:
+------------------------+---------------------------------------------------+-------------------------------------------------------------+ +------------------------+---------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes | | File | Location | Notes |
@ -154,260 +109,88 @@ Both CMake and traditional make build options offer ways to automate these tasks
| LAMMPS shared library | * ``/usr/lib/`` (32bit) | | | LAMMPS shared library | * ``/usr/lib/`` (32bit) | |
| | * ``/usr/lib64/`` (64bit) | | | | * ``/usr/lib64/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+ +------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | ``/usr/bin/`` | | | LAMMPS executable | * ``/usr/bin/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+ +------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | ``/usr/share/lammps/potentials/`` | | | LAMMPS potential files | * ``/usr/share/lammps/potentials/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+ +------------------------+---------------------------------------------------+-------------------------------------------------------------+
The following is a minimal working example: 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.
1. Install LAMMPS shared library and Python module into system folder .. code-block:: bash
.. code-block:: bash # Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# configure LAMMPS compilation # MacOS
# compile with shared library, PYTHON package, and C++ exceptions export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
# TODO: add more options to customize your LAMMPS installation
cmake -C ../cmake/presets/minimal.cmake \
-D BUILD_SHARED_LIBS=on \
-D PKG_PYTHON=on \
-D LAMMPS_EXCEPTIONS=on \
-D CMAKE_INSTALL_PREFIX=/usr \
../cmake
# compile LAMMPS (in parallel for faster builds) If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
cmake --build . --parallel also need to adjust the ``PATH`` environment variable (but many
newer Linux distributions already have ``$HOME/.local/bin``
included). Example:
# install LAMMPS into /usr (requires write access) .. code-block:: bash
sudo cmake --install .
Unlike the local user installation, no additional environment export PATH=$HOME/.local/bin:$PATH
variables need to be set. The system locations such as ``/usr/lib``, and
``/usr/lib64`` are already part of the search path of the dynamic library
loader. Therefore ``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS) does not
have be set. The same is true for ``PATH``.
All other environment variables will be automatically set when To make those changes permanent, you can add the commands to your
launching a new shell. This is due to files installed in system folders ``$HOME/.bashrc`` file. For a system-wide installation is is not
``/etc/profile.d/``, such as ``/etc/profile.d/lammps.sh``, that are loaded when a necessary due to files installed in system folders that are loaded
login shell is started. automatically when a login shell is started.
2. Open a new shell .. tab:: Python module only
Close the current shell and open a new one or use ``source /etc/profile`` to Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
update your environment :doc:`traditional make <Build_make>` procedure in :ref:`shared
mode <exe>`. After compilation has finished type (in the
compilation folder):
.. note:: .. code-block:: bash
On some systems you might also need to log out your current user and log back in. make install-python
3. Verify if LAMMPS can be successfully started from Python This will try to install (only) the shared library and the python
module into a system folder and if that fails (due to missing
Open a new terminal and test if LAMMPS can be started from within Python: write permissions) will instead do the installation to a user
folder under ``$HOME/.local``. For a system-wide installation you
.. code-block:: bash would have to gain superuser privilege, e.g. though ``sudo``
$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import lammps
>>> lmp = lammps.lammps()
LAMMPS (18 Sep 2020)
using 1 OpenMP thread(s) per MPI task
>>>
.. note::
If you recompile LAMMPS, you will have to also rerun the install step to
ensure the latest Python module and shared library are installed.
.. tab:: CMake (virtual environment)
LAMMPS and its Python module can be installed together into a
Python virtual environment.
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 <python_pep405>`_ for more
information.
To install into the virtual environment, it is first activated and the
``CMAKE_INSTALL_PREFIX`` is set to value of the ``$VIRTUAL_ENV`` environment
variable. This leads to the following installation locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes | | File | Location | Notes |
+========================+===========================================================+=============================================================+ +========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version | | LAMMPS Python Module | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | | | | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | | | LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | | | | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | ``$VIRTUAL_ENV/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | ``$VIRTUAL_ENV/share/lammps/potentials/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+ +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
The following is a minimal working example using CMake: For a system-wide installation those folders would then become.
1. Create a virtual environment +------------------------+---------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===================================================+=============================================================+
| LAMMPS Python Module | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
Use the `venv <python_venv>`_ module to create a new environment No environment variables need to be set for those, as those
inside of the folder ``$HOME/myenv``. For Python versions prior 3.3, folders are searched by default by Python or the LAMMPS Python
you can use `virtualenv <python_virtualenv>`_ instead. module.
.. code-block:: bash For the traditional make process you can override the python
version to version x.y when calling ``make`` with
# create virtual environment in folder $HOME/myenv ``PYTHON=pythonX.Y``. For a CMake based compilation this choice
python3 -m venv $HOME/myenv has to be made during the CMake configuration step.
2. Modify the ``$HOME/myenv/bin/activate`` script
The ``activate`` script initializes the environment for use. For convenience,
add two additional lines at the end of this script:
* To allow the dynamic library loader to find the LAMMPS shared library, add
the folder where it will be installed to ``LD_LIBRARY_PATH`` environment
variable (``DYLD_LIBRARY_PATH`` on MacOS). When installing LAMMPS into a
virtual environment this location will be ``$VIRTUAL_ENV/lib``.
Run the following command to add the necessary line to the ``activate`` script:
.. code-block:: bash
# 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
* Any LAMMPS installation will need to know the location of the folder containing its potential files.
This can be set with the ``LAMMPS_POTENTIALS`` environment variable. When installing LAMMPS into a
virtual environment this location will be ``$VIRTUAL_ENV/share/lammps/potentials``.
Run the following command to add the change in the ``activate`` script:
.. code-block:: bash
echo 'export LAMMPS_POTENTIALS=$VIRTUAL_ENV/share/lammps/potentials' >> $HOME/myenv/bin/activate
3. Compile LAMMPS and install it into virtual environment
.. code-block:: bash
# create and change into build directory
mkdir build
cd build
# activate environment, this sets VIRTUAL_ENV and other environment variables
source $HOME/myenv/bin/activate
# configure LAMMPS compilation
# compile with shared library, PYTHON package, and C++ exceptions
# and install into virtual environment folder (VIRTUAL_ENV)
# TODO: add more options to customize your LAMMPS installation
(myenv)$ cmake -C ../cmake/presets/minimal.cmake \
-D BUILD_SHARED_LIBS=on \
-D PKG_PYTHON=on \
-D LAMMPS_EXCEPTIONS=on \
-D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV \
../cmake
# compile LAMMPS (in parallel for faster builds)
(myenv)$ cmake --build . --parallel
# install LAMMPS into myenv
(myenv)$ cmake --install .
4. Verify if LAMMPS can be successfully started from Python
.. code-block:: bash
(myenv)$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import lammps
>>> lmp = lammps.lammps()
LAMMPS (18 Sep 2020)
using 1 OpenMP thread(s) per MPI task
>>>
.. note::
If you recompile LAMMPS, you will have to also rerun the install step to
ensure the virtual environment contains the latest Python module and shared
library.
.. tab:: Traditional make
Instructions on how to build LAMMPS as a shared library are given on
the :doc:`Build_basics <Build_basics>` doc page. A shared library is
one that is dynamically loadable, which is what Python requires to
wrap LAMMPS. On Linux this is a library file that ends in ``.so``, not
``.a``.
From the ``src`` directory, type
.. code-block:: bash
make foo mode=shared
where ``foo`` is the machine target name, such as ``mpi`` or ``serial``.
This should create the file ``liblammps_foo.so`` in the ``src`` directory, as
well as a soft link ``liblammps.so``, which is what the Python wrapper will
load by default. Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.
.. note::
If you are building LAMMPS with an MPI or FFT library or other
auxiliary libraries (used by various packages), then all of these
extra libraries must also be shared libraries. If the LAMMPS
shared-library build fails with an error complaining about this, see
the :doc:`Build_basics <Build_basics>` doc page.
You can achieve that Python can find these files in one of two ways:
* set two environment variables pointing to the location in the source tree
* run ``make install-python`` or run the ``python/install.py`` script explicitly
When calling ``make install-python`` LAMMPS will try to install the
python module and the shared library into the python site-packages folders;
either the system-wide ones, or the local users ones (in case of insufficient
permissions for the global install). Python will then find the module
and shared library file automatically. The exact location of these folders
depends on your python version and your operating system.
You can override the python version to version x.y when calling
``make`` with ``PYTHON=pythonX.Y``.
If you set the paths to these files as environment variables, you only
have to do it once. For the csh or tcsh shells, add something like
this to your ``~/.cshrc`` file, one line for each of the two files:
.. code-block:: csh
setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src
On MacOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
For Bourne/Korn shells accordingly into the corresponding files using
the ``export`` shell builtin.
If you use ``make install-python`` or the ``python/install.py`` script, you need
to invoke it every time you rebuild LAMMPS (as a shared library) or
make changes to the ``python/lammps.py`` file, so that the site-packages
files are updated with the new version.
If the default settings of ``make install-python`` are not what you want, If the default settings of ``make install-python`` are not what you want,
you can invoke ``install.py`` from the python directory manually as you can invoke ``install.py`` from the python directory manually as
@ -423,14 +206,156 @@ Both CMake and traditional make build options offer ways to automate these tasks
If you use a legacy installation folder, you will need to set your If you use a legacy installation folder, you will need to set your
``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment ``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment
variables accordingly, as described above. variables accordingly as explained in the description for "In place use".
Note that if you want Python to be able to load different versions of .. tab:: Virtual environment
the LAMMPS shared library (see :ref:`python_create_lammps`), you will
need to manually copy files like ``liblammps_mpi.so`` into the appropriate
system directory. This is not needed if you set the ``LD_LIBRARY_PATH``
environment variable as described above.
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 <python_pep405>`_ for more
information.
To create a virtual environment in the folder ``$HOME/myenv``,
use the `venv <python_venv>`_ module as follows.
.. code-block:: bash
# create virtual environment in folder $HOME/myenv
python3 -m venv $HOME/myenv
For Python versions prior 3.3 you can use `virtualenv
<python_virtualenv>`_ command instead of "python3 -m venv". This
step has to be done only once.
To activate the virtual environment type:
.. code-block:: bash
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 | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
If you do a full installation (CMake only) with "install", this
leads to the following installation locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
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:
.. code-block:: bash
# 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
.. tab:: In place usage
You can also :doc:`compile LAMMPS <Build>` as usual in
:ref:`"shared" mode <exe>` 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:
.. code-block:: bash
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:
.. code-block:: csh
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:
.. code-block:: bash
$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import lammps
>>> lmp = lammps.lammps()
LAMMPS (18 Sep 2020)
using 1 OpenMP thread(s) per MPI task
>>>
.. note::
Unless you opted for "In place use", you will have to rerun the installation
any time you recompile LAMMPS to ensure the latest Python module and shared
library are installed and used.
.. note::
If you want Python to be able to load different versions of the
LAMMPS shared library with different settings, you will need to
manually copy the files under different names
(e.g. ``liblammps_mpi.so`` or ``liblammps_gpu.so``) into the
appropriate folder as indicated above. You can then select the
desired library through the *name* argument of the LAMMPS object
constructor (see :ref:`python_create_lammps`).
.. _python_install_mpi4py: .. _python_install_mpi4py:
@ -451,49 +376,60 @@ and as of version 2.0.0 mpi4py allows passing a custom MPI communicator
to the LAMMPS constructor, which means one can easily run one or more to the LAMMPS constructor, which means one can easily run one or more
LAMMPS instances on subsets of the total MPI ranks. LAMMPS instances on subsets of the total MPI ranks.
Install mpi4py via ``pip`` (version 3.0.3 as of Sep 2020): Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as
follows:
.. tabs:: - Via ``pip`` into a local user folder with:
.. tab:: local user .. code-block:: bash
.. code-block:: bash pip install --user mpi4py
pip install --user mpi4py - Via ``dnf`` into a system folder for RedHat/Fedora systems:
.. tab:: system-wide .. code-block:: bash
.. code-block:: bash # for use with OpenMPI
sudo dnf install python3-mpi4py-openmpi
# for use with MPICH
sudo dnf install python3-mpi4py-openmpi
sudo pip install mpi4py - Via ``pip`` into a system folder (not recommended):
.. tab:: virtual environment .. code-block:: bash
.. code-block:: bash sudo dnf install mpi4py
$ source $HOME/myenv/activate - Via ``pip`` into a virtual environment (see above):
(myenv)$ pip install mpi4py
.. code-block:: bash
$ source $HOME/myenv/activate
(myenv)$ pip install mpi4py
.. _mpi4py_install: https://mpi4py.readthedocs.io/en/stable/install.html .. _mpi4py_install: https://mpi4py.readthedocs.io/en/stable/install.html
For more detailed installation instructions, please see the `mpi4py installation <mpi4py_install>`_ page. For more detailed installation instructions and additional options,
please see the `mpi4py installation <mpi4py_install>`_ page.
.. note:: .. note::
To use mpi4py and LAMMPS in parallel from Python, you must To use ``mpi4py`` and LAMMPS in parallel from Python, you must make
insure both are using the same version of MPI. If you only have one certain that both are using the same implementation and version of an
MPI installed on your system, this is not an issue, but it can be if MPI library. If you only have one MPI library installed on your
you have multiple MPIs. Your LAMMPS build is explicit about which MPI system, this is not an issue, but it can be if you have multiple MPI
it is using, since it is either detected during CMake configuration or installations (e.g. on an HPC cluster to be selected through
in the traditional make build system you specify the details in your environment modules). Your LAMMPS build is explicit about which MPI
low-level ``src/MAKE/Makefile.foo`` file. it is using, since it is either detected during CMake configuration
mpi4py uses the ``mpicc`` command to find or in the traditional make build system you specify the details in
information about the MPI it uses to build against. And it tries to your low-level ``src/MAKE/Makefile.foo`` file. The installation
load "libmpi.so" from the ``LD_LIBRARY_PATH``. This may or may not find process of ``mpi4py`` uses the ``mpicc`` command to find information
about the MPI it uses to build against. And it tries to load
"libmpi.so" from the ``LD_LIBRARY_PATH``. This may or may not find
the MPI library that LAMMPS is using. If you have problems running the MPI library that LAMMPS is using. If you have problems running
both mpi4py and LAMMPS together, this is an issue you may need to both mpi4py and LAMMPS together, this is an issue you may need to
address, e.g. by moving other MPI installations so that mpi4py finds address, e.g. by loading the module for different MPI installation so
the right one. that mpi4py finds the right one.
If you have successfully installed mpi4py, you should be able to run If you have successfully installed mpi4py, you should be able to run
Python and type Python and type

1
doc/utils/sphinx-config/false_positives.txt
View File

@ -3285,6 +3285,7 @@ vectorized
Vegt Vegt
vel vel
Velázquez Velázquez
venv
Verlag Verlag
verlet verlet
Verlet Verlet