diff --git a/doc/src/Python_examples.rst b/doc/src/Python_examples.rst index 25cb4f8a77..60184bc450 100644 --- a/doc/src/Python_examples.rst +++ b/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 | -+----------------------------------------------------------------+--------------------------------------------------+ -| demo.py | invoke various LAMMPS library interface routines | -+----------------------------------------------------------------+--------------------------------------------------+ -| simple.py | run in parallel | -+----------------------------------------------------------------+--------------------------------------------------+ -| similar to examples/COUPLE/simple/simple.cpp | split.py | -+----------------------------------------------------------------+--------------------------------------------------+ -| same as simple.py but running in parallel on a subset of procs | gui.py | -+----------------------------------------------------------------+--------------------------------------------------+ -| GUI go/stop/temperature-slider to control LAMMPS | plot.py | -+----------------------------------------------------------------+--------------------------------------------------+ -| real-time temperature plot with GnuPlot via Pizza.py | viz_tool.py | -+----------------------------------------------------------------+--------------------------------------------------+ -| real-time viz via some viz package | vizplotgui_tool.py | -+----------------------------------------------------------------+--------------------------------------------------+ -| combination of viz_tool.py and plot.py and gui.py | | -+----------------------------------------------------------------+--------------------------------------------------+ ++------------------------+--------------------------------------------------------------------+ +| ``trivial.py`` | read/run a LAMMPS input script through Python | ++------------------------+--------------------------------------------------------------------+ +| ``demo.py`` | invoke various LAMMPS library interface routines | ++------------------------+--------------------------------------------------------------------+ +| ``simple.py`` | run in parallel, similar to ``examples/COUPLE/simple/simple.cpp`` | ++------------------------+--------------------------------------------------------------------+ +| ``split.py`` | same as ``simple.py`` but running in parallel on a subset of procs | ++------------------------+--------------------------------------------------------------------+ +| ``gui.py`` | GUI go/stop/temperature-slider to control LAMMPS | ++------------------------+--------------------------------------------------------------------+ +| ``plot.py`` | real-time temperature plot with GnuPlot via Pizza.py | ++------------------------+--------------------------------------------------------------------+ +| ``viz_TOOL.py`` | real-time viz via some viz package | ++------------------------+--------------------------------------------------------------------+ +| ``vizplotgui_TOOL.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 `_ 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: 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 `_ or `here `_ for more details: +AtomEye web pages for more details: -.. parsed-literal:: - - http://li.mit.edu/Archive/Graphics/A/ - http://li.mit.edu/Archive/Graphics/A3/A3.html +* `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 `_ or -`here `_ for more details: +from a Python script. See the PyMol web pages for more details: -.. parsed-literal:: - - https://www.pymol.org - https://github.com/schrodinger/pymol-open-source + * `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 `_ 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 diff --git a/doc/src/Python_execute.rst b/doc/src/Python_execute.rst index 309b2b56e0..59faa34438 100644 --- a/doc/src/Python_execute.rst +++ b/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 `: .. 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. - For the ``region`` command that means the :code:`region()` method can be called. + These parts are then passed to a member function with the name of the :doc:`command `. + For the :doc:`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 - PyLammps interface takes the entire parameter list and transparently - merges it to a single command string. + In the latter example, all parameters except the first are Python floating-point literals. The + member function takes the entire parameter list and transparently merges it to a single command + string. The benefit of this approach is avoiding redundant command calls and easier - parameterization. In the original interface parameterization this needed to be done - manually by creating formatted strings. + parameterization. In the lammps API parameterization needed to be done + 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. diff --git a/doc/src/Python_launch.rst b/doc/src/Python_launch.rst index 02963c945e..500a107977 100644 --- a/doc/src/Python_launch.rst +++ b/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() diff --git a/doc/src/Python_run.rst b/doc/src/Python_run.rst index 3e0d52f7ac..2bdc39f58a 100644 --- a/doc/src/Python_run.rst +++ b/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 diff --git a/doc/src/pair_eam.rst b/doc/src/pair_eam.rst index 690b387bad..e2b6957032 100644 --- a/doc/src/pair_eam.rst +++ b/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 rho(r) for element I at element 2 +* density function :math:`\rho_{1\beta} (r)` for element :math:`\beta` at element 1 (Nr values) +* 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 -file. +asymmetric (:math:`\rho_{\alpha\beta} (r) \neq \rho_{\beta\alpha} (r)` ) +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