ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #2429 from rbberger/python_docs

Browse Source 
Minor updates to the Python docs
This commit is contained in:
Axel Kohlmeyer
2020-10-20 21:12:44 -04:00
committed by GitHub
parent 955c7c1efb cd605d46bc
commit 4b447fb3d8
4 changed files with 59 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
doc/src/Python_examples.rst
View File

@ -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 <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/
http://li.mit.edu/Archive/Graphics/A3/A3.html
* `http://li.mit.edu/Archive/Graphics/A/ <atomeye_>`_
* `http://li.mit.edu/Archive/Graphics/A3/A3.html <atomeye3_>`_
.. _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
`here <pymolopen_>`_ 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 <pymolhome_>`_
* `https://github.com/schrodinger/pymol-open-source <pymolopen_>`_
.. _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

31
doc/src/Python_execute.rst
View File

@ -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.
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 <Commands_all>`.
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
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.

2
doc/src/Python_launch.rst
View File

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

6
doc/src/Python_run.rst
View File

@ -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