Merge branch 'master' into swig-wrappers

doc/src/Python_examples.rst

@@ -10,45 +10,41 @@ things that are possible when Python wraps LAMMPS.  If you create your
 own scripts, send them to us and we can include them in the LAMMPS
 distribution.
 
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| trivial.py                                                     | read/run a LAMMPS input script through Python    |
+| ``trivial.py``         | read/run a LAMMPS input script through Python                      |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| demo.py                                                        | invoke various LAMMPS library interface routines |
+| ``demo.py``            | invoke various LAMMPS library interface routines                   |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| simple.py                                                      | run in parallel                                  |
+| ``simple.py``          | run in parallel, similar to ``examples/COUPLE/simple/simple.cpp``  |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| similar to examples/COUPLE/simple/simple.cpp                   | split.py                                         |
+| ``split.py``           | same as ``simple.py`` but running in parallel on a subset of procs |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| same as simple.py but running in parallel on a subset of procs | gui.py                                           |
+| ``gui.py``             | GUI go/stop/temperature-slider to control LAMMPS                   |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| GUI go/stop/temperature-slider to control LAMMPS               | plot.py                                          |
+| ``plot.py``            | real-time temperature plot with GnuPlot via Pizza.py               | 
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| real-time temperature plot with GnuPlot via Pizza.py           | viz_tool.py                                      |
+| ``viz_TOOL.py``        | real-time viz via some viz package                                 |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| real-time viz via some viz package                             | vizplotgui_tool.py                               |
+| ``vizplotgui_TOOL.py`` | combination of ``viz_TOOL.py`` and ``plot.py`` and ``gui.py``      |
-+----------------------------------------------------------------+--------------------------------------------------+
++------------------------+--------------------------------------------------------------------+
-| combination of viz_tool.py and plot.py and gui.py             |                                                   |
-+----------------------------------------------------------------+--------------------------------------------------+
 
-----------
+For the ``viz_TOOL.py`` and ``vizplotgui_TOOL.py`` commands, replace ``TOOL``
-
+with ``gl`` or ``atomeye`` or ``pymol`` or ``vmd``, depending on what
-For the ``viz_tool.py`` and ``vizplotgui_tool.py`` commands, replace "tool"
-with "gl" or "atomeye" or "pymol" or "vmd", depending on what
 visualization package you have installed.
 
 Note that for GL, you need to be able to run the Pizza.py GL tool,
-which is included in the pizza sub-directory.  See the `Pizza.py doc pages <pizza_>`_ for more info:
+which is included in the pizza sub-directory.  See the Pizza.py doc pages for more info:
+
+* `https://pizza.sandia.gov <pizza_>`_
 
 .. _pizza: https://pizza.sandia.gov
 
 Note that for AtomEye, you need version 3, and there is a line in the
 scripts that specifies the path and name of the executable.  See the
-AtomEye WWW pages `here <atomeye_>`_ or `here <atomeye3_>`_ for more details:
+AtomEye web pages for more details:
 
-.. parsed-literal::
+* `http://li.mit.edu/Archive/Graphics/A/ <atomeye_>`_
-
+* `http://li.mit.edu/Archive/Graphics/A3/A3.html <atomeye3_>`_
-   http://li.mit.edu/Archive/Graphics/A/
-   http://li.mit.edu/Archive/Graphics/A3/A3.html
 
 .. _atomeye: http://li.mit.edu/Archive/Graphics/A/
 
@@ -59,13 +55,10 @@ capability needed by these Python scripts.
 
 Note that for PyMol, you need to have built and installed the
 open-source version of PyMol in your Python, so that you can import it
-from a Python script.  See the PyMol WWW pages `here <pymolhome_>`_ or
+from a Python script.  See the PyMol web pages for more details:
-`here <pymolopen_>`_ for more details:
 
-.. parsed-literal::
+ * `https://www.pymol.org <pymolhome_>`_
-
+ * `https://github.com/schrodinger/pymol-open-source <pymolopen_>`_
-   https://www.pymol.org
-   https://github.com/schrodinger/pymol-open-source
 
 .. _pymolhome: https://www.pymol.org
 
@@ -74,15 +67,15 @@ from a Python script.  See the PyMol WWW pages `here <pymolhome_>`_ or
 The latter link is to the open-source version.
 
 Note that for VMD, you need a fairly current version (1.8.7 works for
-me) and there are some lines in the pizza/vmd.py script for 4 PIZZA
+me) and there are some lines in the ``pizza/vmd.py`` script for 4 PIZZA
 variables that have to match the VMD installation on your system.
 
 ----------
 
-See the python/README file for instructions on how to run them and the
+See the ``python/README`` file for instructions on how to run them and the
 source code for individual scripts for comments about what they do.
 
-Here are screenshots of the vizplotgui_tool.py script in action for
+Here are screenshots of the ``vizplotgui_tool.py`` script in action for
 different visualization package options:
 
 .. |pyex1| image:: img/screenshot_gl.jpg

doc/src/Python_execute.rst

@@ -57,34 +57,45 @@ it is possible to "compute" what the next LAMMPS command should be.
 
          region box block 0 10 0 5 -0.5 0.5
 
-      can be executed using with the lammps AI with the following Python code if *L* is an
+      can be executed using with the lammps API with the following Python code if ``lmp`` is an
       instance of :py:class:`lammps <lammps.lammps>`:
 
       .. code-block:: Python
 
-         L.command("region box block 0 10 0 5 -0.5 0.5")
+         from lammps import lammps
+
+         lmp = lammps()
+         lmp.command("region box block 0 10 0 5 -0.5 0.5")
 
       With the PyLammps interface, any LAMMPS command can be split up into arbitrary parts.
-      These parts are then passed to a member function with the name of the command.
+      These parts are then passed to a member function with the name of the :doc:`command <Commands_all>`.
-      For the ``region`` command that means the :code:`region()` method can be called.
+      For the :doc:`region <region>` command that means the :code:`region()` method can be called.
       The arguments of the command can be passed as one string, or
       individually.
 
       .. code-block:: Python
 
+         from lammps import PyLammps
+
+         L = PyLammps()
+
+         # pass command parameters as one string
+         L.region("box block 0 10 0 5 -0.5 0.5")
+
+         # OR pass them individually
          L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
 
-      In this example all parameters except the first are Python floating-point literals. The
+      In the latter example, all parameters except the first are Python floating-point literals. The
-      PyLammps interface takes the entire parameter list and transparently
+      member function takes the entire parameter list and transparently merges it to a single command
-      merges it to a single command string.
+      string.
 
       The benefit of this approach is avoiding redundant command calls and easier
-      parameterization. In the original interface parameterization this needed to be done
+      parameterization. In the lammps API parameterization needed to be done
-      manually by creating formatted strings.
+      manually by creating formatted command strings.
 
       .. code-block:: Python
 
-         L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
+         lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
 
       In contrast, methods of PyLammps accept parameters directly and will convert
       them automatically to a final command string.

doc/src/Python_launch.rst

@@ -56,7 +56,7 @@ and you should see the same output as if you had typed
 
 Note that without the mpi4py specific lines from ``test.py``
 
-.. code-block::
+.. code-block:: Python
 
    from lammps import lammps
    lmp = lammps()

doc/src/Python_run.rst

@@ -13,6 +13,12 @@ what functionality is available and give some examples how to use it.
    :maxdepth: 1
 
    Python_launch
+
+------
+
+.. toctree::
+   :maxdepth: 1
+
    Python_create
    Python_execute
    Python_properties

doc/src/pair_eam.rst

@@ -345,8 +345,11 @@ given by
    \rho_{\alpha\beta} (r_{ij})\right) +
    \frac{1}{2} \sum_{j \neq i} \phi_{\alpha\beta} (r_{ij})
 
+where :math:`\rho_{\alpha\beta}` refers to the density contributed 
+by a neighbor atom J of element :math:`\beta` at the site of atom I
+of element :math:`\alpha`. 
 This has the same form as the EAM formula above, except that rho is
-now a functional specific to the atomic types of both atoms I and J,
+now a functional specific to the elements of both atoms I and J,
 so that different elements can contribute differently to the total
 electron density at an atomic site depending on the identity of the
 element at that atomic site.
@@ -393,20 +396,20 @@ have an ".eam.fs" suffix.  They are formatted as follows:
 
 The 5-line header section is identical to an EAM *setfl* file.
 
-Following the header are Nelements sections, one for each element I,
+Following the header are Nelements sections, one for each element :math:`\beta`,
 each with the following format:
 
 * line 1 = atomic number, mass, lattice constant, lattice type (e.g. FCC)
 * embedding function F(rho) (Nrho values)
-* density function rho(r) for element I at element 1 (Nr values)
+* density function :math:`\rho_{1\beta} (r)` for element :math:`\beta` at element 1 (Nr values)
-* density function rho(r) for element I at element 2
+* density function :math:`\rho_{2\beta} (r)` for element :math:`\beta` at element 2
 * ...
-* density function rho(r) for element I at element Nelement
+* density function :math:`\rho_{N_{elem}\beta} (r)` for element :math:`\beta` at element :math:`N_{elem}`
 
 The units of these quantities in line 1 are the same as for *setfl*
 files.  Note that the rho(r) arrays in Finnis/Sinclair can be
-asymmetric (i,j != j,i) so there are Nelements\^2 of them listed in the
+asymmetric (:math:`\rho_{\alpha\beta} (r) \neq \rho_{\beta\alpha} (r)` ) 
-file.
+so there are Nelements\^2 of them listed in the file.
 
 Following the Nelements sections, Nr values for each pair potential
 phi(r) array are listed in the same manner (r\*phi, units of