ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Richard Berger
2020-12-17 11:54:30 -05:00
parent 3103fe85f6
commit f9f9c37bd2
6 changed files with 111 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/Howto_pylammps.rst
View File

@ -9,8 +9,8 @@ Overview
``PyLammps`` is a Python wrapper class for LAMMPS which can be created
on its own or use an existing lammps Python object. It creates a simpler,
more "pythonic" interface to common LAMMPS functionality, in contrast to
the ``lammps.py`` wrapper for the C-style LAMMPS library interface which
is written using `Python ctypes <ctypes_>`_. The ``lammps.py`` wrapper
the ``lammps`` wrapper for the C-style LAMMPS library interface which
is written using `Python ctypes <ctypes_>`_. The ``lammps`` wrapper
is discussed on the :doc:`Python_head` doc page.
Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable

2
doc/src/Python_ext.rst
View File

@ -9,7 +9,7 @@ This means you can extend the Python wrapper by following these steps:
* Add a new interface function to ``src/library.cpp`` and
``src/library.h``.
* Rebuild LAMMPS as a shared library.
* Add a wrapper method to ``python/lammps.py`` for this interface
* Add a wrapper method to ``python/lammps/core.py`` for this interface
function.
* Define the corresponding ``argtypes`` list and ``restype``
in the ``lammps.__init__()`` function.

176
doc/src/Python_install.rst
View File

@ -8,9 +8,9 @@ module. Because of the dynamic loading, it is required that LAMMPS is
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 components are necessary for Python to be able to invoke LAMMPS code:
* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
* The LAMMPS Python Package (``lammps``) from the ``python`` folder
* The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or
``liblammps.dll``) from the folder where you compiled LAMMPS.
@ -25,10 +25,10 @@ Installing the LAMMPS Python Module and Shared Library
======================================================
Making LAMMPS usable within Python and vice versa requires putting the
LAMMPS Python module file (``lammps.py``) into a location where the
LAMMPS Python package (``lammps``) 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
into a folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve
this.
#. Do a full LAMMPS installation of libraries, executables, selected
@ -36,13 +36,13 @@ this.
available via CMake), which can also be either system-wide or into
user specific folders.
#. Install both files into a Python ``site-packages`` folder, either
#. Install both components 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 an installation into a virtual environment. This can either be
an installation of the python module only or a full installation.
#. Do an installation into a virtual environment. This can either be an
installation of the Python package only or a full installation of LAMMPS.
#. Leave the files where they are in the source/development tree and
adjust some environment variables.
@ -81,19 +81,19 @@ this.
This leads to an installation to the following locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | |
| | * ``$HOME/.local/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$HOME/.local/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | |
| | * ``$HOME/.local/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$HOME/.local/bin/`` | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/`` | 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
@ -102,19 +102,19 @@ this.
privilege, e.g. by using ``sudo cmake --install .``. The
installation folders will then by changed to:
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| 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/`` (32bit) | |
| | * ``/usr/lib64/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``/usr/bin/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``/usr/share/lammps/potentials/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/`` (32bit) | |
| | * ``/usr/lib64/`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``/usr/bin/`` | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``/usr/share/lammps/potentials/`` | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
To be able to use the "user" installation you have to ensure that
the folder containing the LAMMPS shared library is either included
@ -146,7 +146,7 @@ this.
necessary due to files installed in system folders that are loaded
automatically when a login shell is started.
.. tab:: Python module only
.. tab:: Python package only
Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
:doc:`traditional make <Build_make>` procedure in :ref:`shared
@ -157,37 +157,37 @@ this.
make install-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
This will try to install (only) the shared library and the Python
package 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 | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation those folders would then become.
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| 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) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
No environment variables need to be set for those, as those
folders are searched by default by Python or the LAMMPS Python
module.
package.
For the traditional make process you can override the python
version to version x.y when calling ``make`` with
@ -199,9 +199,9 @@ this.
.. code-block:: bash
$ python install.py -m <python module> -l <shared library> -v <version.h file> [-d <pydir>]
$ python install.py -p <python package> -l <shared library> -v <version.h file> [-d <pydir>]
* The ``-m`` flag points to the ``lammps.py`` python module file to be installed,
* The ``-p`` flag points to the ``lammps`` Python package folder 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
@ -249,38 +249,38 @@ this.
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"
traditional make procedure, no additional steps are needed.
After compiling LAMMPS you can do a "Python package only"
installation with ``make install-python`` and the LAMMPS Python
module and the shared library file are installed into the
package 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) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (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/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (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
@ -302,9 +302,9 @@ this.
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
package 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
variables ``PYTHONPATH`` (for the Python package) and
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
For Bourne shells (bash, ksh and similar) the commands are:
@ -325,6 +325,10 @@ this.
You can make those changes permanent by editing your ``$HOME/.bashrc``
or ``$HOME/.login`` files, respectively.
.. note::
The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package!
To verify if LAMMPS can be successfully started from Python, start the
Python interpreter, load the ``lammps`` Python module and create a
@ -346,7 +350,7 @@ output similar to the following:
.. 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
any time you recompile LAMMPS to ensure the latest Python package and shared
library are installed and used.
.. note::

10
doc/src/Python_overview.rst
View File

@ -2,9 +2,9 @@ Overview
========
The LAMMPS distribution includes a ``python`` directory with the Python
code needed to run LAMMPS from Python. The ``python/lammps.py``
contains :doc:`the "lammps" Python <Python_module>` that wraps the
LAMMPS C-library interface. This file makes it is possible to do the
code needed to run LAMMPS from Python. The ``python/lammps`` package
contains :doc:`the "lammps" Python module <Python_module>` that wraps the
LAMMPS C-library interface. This module makes it is possible to do the
following either from a Python script, or interactively from a Python
prompt:
@ -20,8 +20,8 @@ have a version of Python that extends Python to enable multiple
instances of Python to read what you type.
To do all of this, you must build LAMMPS in :ref:`"shared" mode <exe>`
and make certain that your Python interpreter can find the ``lammps.py``
file and the LAMMPS shared library file.
and make certain that your Python interpreter can find the ``lammps``
Python package and the LAMMPS shared library file.
.. _ctypes: https://docs.python.org/3/library/ctypes.html

2
doc/src/Python_trouble.rst
View File

@ -33,7 +33,7 @@ the constructor call as follows (see :ref:`python_create_lammps` for more detail
>>> lmp = lammps(name='mpi')
You can also test the load directly in Python as follows, without
first importing from the lammps.py file:
first importing from the ``lammps`` module:
.. code-block:: python

26
doc/src/python.rst
View File

@ -323,8 +323,8 @@ Python function is as follows:
The function definition must include a variable (lmpptr in this case)
which corresponds to SELF in the python command. The first line of the
function imports the Python module lammps.py in the python directory of
the distribution. The second line creates a Python object "lmp" which
function imports the :doc:`"lammps" Python module <Python_module>`.
The second line creates a Python object ``lmp`` which
wraps the instance of LAMMPS that called the function. The "ptr=lmpptr"
argument is what makes that happen. The third line invokes the
command() function in the LAMMPS library interface. It takes a single
@ -502,18 +502,16 @@ Python library on your system. Settings to enable this are in the
lib/python/Makefile.lammps file. See the lib/python/README file for
information on those settings.
If you use Python code which calls back to LAMMPS, via the SELF input
argument explained above, there is an extra step required when
building LAMMPS. LAMMPS must also be built as a shared library and
your Python function must be able to load the Python module in
python/lammps.py that wraps the LAMMPS library interface. These are
the same steps required to use Python by itself to wrap LAMMPS.
Details on these steps are explained on the :doc:`Python <Python_head>`
doc page. Note that it is important that the stand-alone LAMMPS
executable and the LAMMPS shared library be consistent (built from the
same source code files) in order for this to work. If the two have
been built at different times using different source files, problems
may occur.
If you use Python code which calls back to LAMMPS, via the SELF input argument
explained above, there is an extra step required when building LAMMPS. LAMMPS
must also be built as a shared library and your Python function must be able to
load the :doc:`"lammps" Python module <Python_module>` that wraps the LAMMPS
library interface. These are the same steps required to use Python by itself
to wrap LAMMPS. Details on these steps are explained on the :doc:`Python
<Python_head>` doc page. Note that it is important that the stand-alone LAMMPS
executable and the LAMMPS shared library be consistent (built from the same
source code files) in order for this to work. If the two have been built at
different times using different source files, problems may occur.
Related commands
""""""""""""""""