revise python in LAMMPS docs
This commit is contained in:
Axel Kohlmeyer
@ -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,23 +20,28 @@ used together.
|
||||
Python_ext
|
||||
Python_trouble
|
||||
|
||||
If you're not familiar with `Python <http://www.python.org>`_, 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 <http://www.python.org>`_, 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 <Howto_couple>` doc page for more ideas about
|
||||
coupling LAMMPS to other codes. See the :doc:`Howto library <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
|
||||
|
||||
@ -4,12 +4,14 @@ Installation
|
||||
The LAMMPS Python module enables calling the :ref:`LAMMPS C library API <lammps_c_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*.
|
||||
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:
|
||||
|
||||
* 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
|
||||
@ -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 <python_pep405>`_
|
||||
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 <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
|
||||
@ -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
|
||||
|
||||
@ -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 <Python_module>` 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 <exe>`
|
||||
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 <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 <https://www.python.org/doc/sunset-python-2/>`_.
|
||||
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 <https://www.python.org/doc/sunset-python-2/>`_. 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 <Howto_library>`, so
|
||||
wrap LAMMPS through the its :doc:`library interface <Library>`, 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 <lammps.lammps>` can be used indirectly through the provided
|
||||
:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps
|
||||
<lammps.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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -446,7 +446,7 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
|
||||
:py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
|
||||
:py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
|
||||
:py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.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() <lammps.lammps.set_variable()>` method sets an
|
||||
existing string-style variable to a new string value, so that subsequent LAMMPS
|
||||
|
||||
Reference in New Issue
Block a user