diff --git a/doc/src/Howto_pylammps.rst b/doc/src/Howto_pylammps.rst index 89119e89af..e6d3d7b91d 100644 --- a/doc/src/Howto_pylammps.rst +++ b/doc/src/Howto_pylammps.rst @@ -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 `_. The ``lammps.py`` wrapper +the ``lammps`` wrapper for the C-style LAMMPS library interface which +is written using `Python ctypes `_. The ``lammps`` wrapper is discussed on the :doc:`Python_head` doc page. Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable diff --git a/doc/src/Python_ext.rst b/doc/src/Python_ext.rst index 6b6d1ab715..8966ffcb2a 100644 --- a/doc/src/Python_ext.rst +++ b/doc/src/Python_ext.rst @@ -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. diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst index 88d32895a3..0ebc1c49c3 100644 --- a/doc/src/Python_install.rst +++ b/doc/src/Python_install.rst @@ -8,9 +8,9 @@ module. Because of the dynamic loading, it is required that LAMMPS is compiled in :ref:`"shared" mode `. It is also recommended to compile LAMMPS with :ref:`C++ 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 ` or the :doc:`traditional 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 -l -v [-d ] + $ python install.py -p -l -v [-d ] - * 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 ` as usual in :ref:`"shared" mode ` 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:: diff --git a/doc/src/Python_overview.rst b/doc/src/Python_overview.rst index a90ea171d5..2dfc193f8d 100644 --- a/doc/src/Python_overview.rst +++ b/doc/src/Python_overview.rst @@ -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 ` 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 ` 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 ` -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 diff --git a/doc/src/Python_trouble.rst b/doc/src/Python_trouble.rst index 3ef7dacf34..b94a043a6a 100644 --- a/doc/src/Python_trouble.rst +++ b/doc/src/Python_trouble.rst @@ -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 diff --git a/doc/src/python.rst b/doc/src/python.rst index f38e756232..a4c3d7097c 100644 --- a/doc/src/python.rst +++ b/doc/src/python.rst @@ -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 `. +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 ` -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 ` 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 +` 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 """"""""""""""""