diff --git a/doc/src/Python_head.rst b/doc/src/Python_head.rst index e78e727a10..99d005dd97 100644 --- a/doc/src/Python_head.rst +++ b/doc/src/Python_head.rst @@ -1,8 +1,8 @@ Use Python with LAMMPS ********************** -These doc pages describe various ways that LAMMPS and Python can be -used together. +These pages describe various ways that LAMMPS and Python can be used +together. .. toctree:: :maxdepth: 1 @@ -20,26 +20,31 @@ used together. Python_ext Python_trouble -If you're not familiar with `Python `_, it's a -powerful scripting and programming language which can do most -everything that lower-level languages like C or C++ can do in fewer -lines of code. The only drawback is slower execution speed. Python -is also easy to use as a "glue" language to drive a program through -its library interface, or to hook multiple pieces of software -together, such as a simulation code plus a visualization tool, or to -run a coupled multiscale or multiphysics model. +If you are not familiar with `Python `_, it is a +powerful scripting and programming language which can do almost +everything that compiled languages like C, C++, or Fortran can do in +fewer lines of code. It also comes with a large collection of add-on +modules for many purposes (either bundled or easily installed from +Python code repositories). The major drawback is slower execution speed +of the script code compared to compiled programming languages. But when +the script code is interfaced to optimized compiled code, performance can +be on par with a standalone executable, for as long as the scripting is +restricted to high-level operations. Thus Python is also convenient to +use as a "glue" language to "drive" a program through its library +interface, or to hook multiple pieces of software together, such as a +simulation code and a visualization tool, or to run a coupled +multi-scale or multi-physics model. -See the :doc:`Howto_couple ` doc page for more ideas about -coupling LAMMPS to other codes. See the :doc:`Howto library ` doc page for a description of the LAMMPS -library interface provided in src/library.h and src/library.h. That -interface is exposed to Python either when calling LAMMPS from Python -or when calling Python from a LAMMPS input script and then calling -back to LAMMPS from Python code. The library interface is designed to -be easy to add functionality to. Thus the Python interface to LAMMPS -is also easy to extend as well. +See the :doc:`Howto_couple` page for more ideas about coupling LAMMPS +to other codes. See the :doc:`Library` page for a description of the +LAMMPS library interfaces. That interface is exposed to Python either +when calling LAMMPS from Python or when calling Python from a LAMMPS +input script and then calling back to LAMMPS from Python code. The +C-library interface is designed to be easy to add functionality to, +thus the Python interface to LAMMPS is easy to extend as well. If you create interesting Python scripts that run LAMMPS or interesting Python functions that can be called from a LAMMPS input script, that you think would be generally useful, please post them as a pull request to our `GitHub site `_, -and they can be added to the LAMMPS distribution or webpage. +and they can be added to the LAMMPS distribution or web page. diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst index ce0bfec346..5c244e6c16 100644 --- a/doc/src/Python_install.rst +++ b/doc/src/Python_install.rst @@ -3,13 +3,15 @@ Installation 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 -Python ``ctypes`` module. Because of the dynamic loading, it is required that -LAMMPS is compiled in *shared mode*. +Python ``ctypes`` 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: -* LAMMPS Python Module (``python/lammps.py``) -* LAMMPS Shared Library (e.g., ``liblammps.so``) +* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder +* The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or ``liblammps.dll``) + from the folder where you compiled LAMMPS. .. _python_virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment @@ -24,7 +26,7 @@ Installing the LAMMPS Python Module and Shared Library Making LAMMPS usable within Python and vice versa requires putting the LAMMPS Python module into a location that the Python interpreter can find and installing the LAMMPS shared library into a folder that the dynamic loader -searches. For some potentials LAMMPS also needs to know where it can find the +searches. For some potentials LAMMPS also needs to know where it can find the necessary potential files. Both CMake and traditional make build options offer ways to automate these tasks. @@ -225,13 +227,17 @@ Both CMake and traditional make build options offer ways to automate these tasks LAMMPS and its Python module can be installed together into a Python virtual environment. - A virtual environment is a minimalistic Python installation inside of a - folder. It allows isolating and customizing a Python environment that is - independent from a user or system installation. This gives you the flexibility - to install (newer) 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. + 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 install into the virtual environment, it is first activated and the ``CMAKE_INSTALL_PREFIX`` is set to value of the ``$VIRTUAL_ENV`` environment @@ -266,7 +272,7 @@ Both CMake and traditional make build options offer ways to automate these tasks 2. Modify the ``$HOME/myenv/bin/activate`` script - The ``activate`` script initializes the environment for use. For convienience, + 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 diff --git a/doc/src/Python_overview.rst b/doc/src/Python_overview.rst index e9aba544f9..cbc656b602 100644 --- a/doc/src/Python_overview.rst +++ b/doc/src/Python_overview.rst @@ -1,42 +1,60 @@ Overview ======== -The LAMMPS distribution includes a python directory with all you need -to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS -library interface, with one wrapper function per LAMMPS library -function. This file makes it is possible to do the following either -from a Python script, or interactively from a Python prompt: create -one or more instances of LAMMPS, invoke LAMMPS commands or give it an -input script, run LAMMPS incrementally, extract LAMMPS results, an -modify internal LAMMPS variables. From a Python script you can do -this in serial or parallel. Running Python interactively in parallel -does not generally work, unless you have a version of Python that -extends Python to enable multiple instances of Python to read what you -type. +The LAMMPS distribution includes a python directory with all you need 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 following either +from a Python script, or interactively from a Python prompt: -To do all of this, you must first build LAMMPS as a shared library, -then insure that your Python can find the python/lammps.py file and -the shared library. +- create one or more instances of LAMMPS +- invoke LAMMPS commands or read them from an input script +- run LAMMPS incrementally +- extract LAMMPS results +- and modify internal LAMMPS data structures. + +From a Python script you can do this in serial or parallel. Running +Python interactively in parallel does not generally work, unless you +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. + +.. _ctypes: https://docs.python.org/3/library/ctypes.html + +The Python wrapper for LAMMPS uses the `ctypes `_ package in +Python, which auto-generates the interface code needed between Python +and a set of C-style library functions. Ctypes has been part of the +standard Python distribution since version 2.5. You can check which +version of Python you have by simply typing "python" at a shell prompt. +Below is an example output for Python version 3.8.5. + +.. code-block:: + + $ python + Python 3.8.5 (default, Aug 12 2020, 00:00:00) + [GCC 10.2.1 20200723 (Red Hat 10.2.1-1)] on linux + Type "help", "copyright", "credits" or "license" for more information. + >>> -The Python wrapper for LAMMPS uses the "ctypes" package in Python, -which auto-generates the interface code needed between Python and a -set of C-style library functions. Ctypes is part of standard Python -for versions 2.5 and later. You can check which version of Python you -have by simply typing "python" at a shell prompt. .. warning:: Python 2 support is deprecated - While the LAMMPS Python module was originally developed to support both - Python 2 and 3, Python 2 is no longer maintained as of `January 1, 2020 `_. - Therefore, we will no longer backport any new features to Python 2 and - highly recommend using Python versions 3.6+. + While the LAMMPS Python module was originally developed to support + both, Python 2 and 3, any new code is only tested with Python 3. + Please note that Python 2 is no longer maintained as of `January 1, + 2020 `_. Therefore, we + highly recommend using Python version 3.6 or later. Compatibility to + Python 2 will be removed eventually. --------- LAMMPS can work together with Python in three ways. First, Python can -wrap LAMMPS through the its :doc:`library interface `, so +wrap LAMMPS through the its :doc:`library interface `, so that a Python script can create one or more instances of LAMMPS and -launch one or more simulations. In Python lingo, this is called +launch one or more simulations. In Python terms, this is referred to as "extending" Python with a LAMMPS module. .. figure:: JPG/python-invoke-lammps.png @@ -45,27 +63,28 @@ launch one or more simulations. In Python lingo, this is called Launching LAMMPS via Python -Second, the lower-level Python interface can be used indirectly through -the provided :code:`PyLammps` and :code:`IPyLammps` wrapper classes, written in Python. -These wrappers try to simplify the usage of LAMMPS in Python by -providing an object-based interface to common LAMMPS functionality. -They also reduces the amount of code necessary to parameterize LAMMPS -scripts through Python and make variables and computes directly -accessible. +Second, the lower-level Python interface in the :py:class:`lammps Python +class ` can be used indirectly through the provided +:py:class:`PyLammps ` and :py:class:`IPyLammps +` wrapper classes, also written in Python. These +wrappers try to simplify the usage of LAMMPS in Python by providing a +more object-based interface to common LAMMPS functionality. They also +reduce the amount of code necessary to parameterize LAMMPS scripts +through Python and make variables and computes directly accessible. .. figure:: JPG/pylammps-invoke-lammps.png :figclass: align-center Using the PyLammps / IPyLammps wrappers -Third, LAMMPS can use the Python interpreter, so that a LAMMPS -input script or styles can invoke Python code directly, and pass -information back-and-forth between the input script and Python -functions you write. This Python code can also callback to LAMMPS -to query or change its attributes through the LAMMPS Python module -mentioned above. In Python lingo, this is "embedding" Python in -LAMMPS. When used in this mode, Python can perform script operations -that the simple LAMMPS input script syntax can not. +Third, LAMMPS can use the Python interpreter, so that a LAMMPS input +script or styles can invoke Python code directly, and pass information +back-and-forth between the input script and Python functions you write. +This Python code can also call back to LAMMPS to query or change its +attributes through the LAMMPS Python module mentioned above. In Python +terms, this is called "embedding" Python into LAMMPS. When used in this +mode, Python can perform script operations that the simple LAMMPS input +script syntax can not. .. figure:: JPG/lammps-invoke-python.png :figclass: align-center diff --git a/doc/src/Python_run.rst b/doc/src/Python_run.rst index 726705e30e..1f91dfadd7 100644 --- a/doc/src/Python_run.rst +++ b/doc/src/Python_run.rst @@ -68,7 +68,7 @@ Note that without the mpi4py specific lines from ``test.py`` running the script with ``mpirun`` on :math:`P` processors would lead to :math:`P` independent simulations to run parallel, each with a single processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS -single processor outputs. that means mpi4py isn't working correctly. +single processor outputs, mpi4py is not working correctly. Also note that once you import the mpi4py module, mpi4py initializes MPI for you, and you can use MPI calls directly in your Python script, as diff --git a/doc/src/Python_usage.rst b/doc/src/Python_usage.rst index 7c23980015..777f226e68 100644 --- a/doc/src/Python_usage.rst +++ b/doc/src/Python_usage.rst @@ -446,7 +446,7 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module. :py:meth:`lammps.numpy.extract_compute() `, :py:meth:`lammps.numpy.extract_fix() `, and :py:meth:`lammps.numpy.extract_variable() ` are - equivlanent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers. + equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers. The :py:meth:`lammps.set_variable() ` method sets an existing string-style variable to a new string value, so that subsequent LAMMPS