revise python in LAMMPS docs

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
+These pages describe various ways that LAMMPS and Python can be used
-used together.
+together.
 
 .. toctree::
    :maxdepth: 1
@@ -20,26 +20,31 @@ used together.
    Python_ext
    Python_trouble
 
-If you're not familiar with `Python <http://www.python.org>`_, it's a
+If you are not familiar with `Python <http://www.python.org>`_, it is a
-powerful scripting and programming language which can do most
+powerful scripting and programming language which can do almost
-everything that lower-level languages like C or C++ can do in fewer
+everything that compiled languages like C, C++, or Fortran can do in
-lines of code.  The only drawback is slower execution speed.  Python
+fewer lines of code. It also comes with a large collection of add-on
-is also easy to use as a "glue" language to drive a program through
+modules for many purposes (either bundled or easily installed from
-its library interface, or to hook multiple pieces of software
+Python code repositories).  The major drawback is slower execution speed
-together, such as a simulation code plus a visualization tool, or to
+of the script code compared to compiled programming languages.  But when
-run a coupled multiscale or multiphysics model.
+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
+See the :doc:`Howto_couple` page for more ideas about coupling LAMMPS
-coupling LAMMPS to other codes.  See the :doc:`Howto library <Howto_library>` doc page for a description of the LAMMPS
+to other codes.  See the :doc:`Library` page for a description of the
-library interface provided in src/library.h and src/library.h.  That
+LAMMPS library interfaces.  That interface is exposed to Python either
-interface is exposed to Python either when calling LAMMPS from Python
+when calling LAMMPS from Python or when calling Python from a LAMMPS
-or when calling Python from a LAMMPS input script and then calling
+input script and then calling back to LAMMPS from Python code.  The
-back to LAMMPS from Python code.  The library interface is designed to
+C-library interface is designed to be easy to add functionality to,
-be easy to add functionality to.  Thus the Python interface to LAMMPS
+thus the Python interface to LAMMPS is easy to extend as well.
-is also 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 <https://github.com/lammps/lammps>`_,
-and they can be added to the LAMMPS distribution or webpage.
+and they can be added to the LAMMPS distribution or web page.

doc/src/Python_install.rst

@@ -3,13 +3,15 @@ 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
+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``)
+* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
-* LAMMPS Shared Library (e.g., ``liblammps.so``)
+* 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
+      A virtual environment is a minimal Python installation inside of a
-      folder. It allows isolating and customizing a Python environment that is
+      folder.  It allows isolating and customizing a Python environment
-      independent from a user or system installation. This gives you the flexibility
+      that is mostly independent from a user or system installation.
-      to install (newer) versions of Python packages that would potentially conflict
+      For the core Python environment, it uses symbolic links to the
-      with already installed system packages. It also does not requite any superuser
+      system installation and thus it can be set up quickly and will not
-      privileges. See `PEP 405: Python Virtual Environments <python_pep405>`_
+      take up much disk space.  This gives you the flexibility to
-      for more information.
+      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

doc/src/Python_overview.rst

@@ -1,42 +1,60 @@
 Overview
 ========
 
-The LAMMPS distribution includes a python directory with all you need
+The LAMMPS distribution includes a python directory with all you need to
-to run LAMMPS from Python.  The python/lammps.py file wraps the LAMMPS
+run LAMMPS from Python.  The ``python/lammps.py`` contains :doc:`the
-library interface, with one wrapper function per LAMMPS library
+"lammps" Python <Python_module>` that wraps the LAMMPS C-library
-function.  This file makes it is possible to do the following either
+interface.  This file makes it is possible to do the following either
-from a Python script, or interactively from a Python prompt: create
+from a Python script, or interactively from a Python prompt:
-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.
 
-To do all of this, you must first build LAMMPS as a shared library,
+- create one or more instances of LAMMPS
-then insure that your Python can find the python/lammps.py file and
+- invoke LAMMPS commands or read them from an input script
-the shared library.
+- 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
+   While the LAMMPS Python module was originally developed to support
-   Python 2 and 3, Python 2 is no longer maintained as of `January 1, 2020 <https://www.python.org/doc/sunset-python-2/>`_.
+   both, Python 2 and 3, any new code is only tested with Python 3.
-   Therefore, we will no longer backport any new features to Python 2 and
+   Please note that Python 2 is no longer maintained as of `January 1,
-   highly recommend using Python versions 3.6+.
+   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
+Second, the lower-level Python interface in the :py:class:`lammps Python
-the provided :code:`PyLammps` and :code:`IPyLammps` wrapper classes, written in Python.
+class <lammps.lammps>` can be used indirectly through the provided
-These wrappers try to simplify the usage of LAMMPS in Python by
+:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps
-providing an object-based interface to common LAMMPS functionality.
+<lammps.IPyLammps>` wrapper classes, also written in Python.  These
-They also reduces the amount of code necessary to parameterize LAMMPS
+wrappers try to simplify the usage of LAMMPS in Python by providing a
-scripts through Python and make variables and computes directly
+more object-based interface to common LAMMPS functionality.  They also
-accessible.
+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
+Third, LAMMPS can use the Python interpreter, so that a LAMMPS input
-input script or styles can invoke Python code directly, and pass
+script or styles can invoke Python code directly, and pass information
-information back-and-forth between the input script and Python
+back-and-forth between the input script and Python functions you write.
-functions you write.  This Python code can also callback to LAMMPS
+This Python code can also call back to LAMMPS to query or change its
-to query or change its attributes through the LAMMPS Python module
+attributes through the LAMMPS Python module mentioned above.  In Python
-mentioned above.  In Python lingo, this is "embedding" Python in
+terms, this is called "embedding" Python into LAMMPS.  When used in this
-LAMMPS.  When used in this mode, Python can perform script operations
+mode, Python can perform script operations that the simple LAMMPS input
-that the simple LAMMPS input script syntax can not.
+script syntax can not.
 
 .. figure:: JPG/lammps-invoke-python.png
    :figclass: align-center

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

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() <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