This directory contains Python code which wraps LAMMPS as a library and allows the LAMMPS library interface to be invoked from Python, either from a Python script or using Python interactively.

Details on the Python interface to LAMMPS and how to build LAMMPS as a shared library, for use with Python, are given in doc/Section_python.html and in doc/Section_start.html#start_5.

Basically you need to follow these steps in the src directory:

% make g++ mode=shlib # build for whatever machine target you wish % make install-python # may need to do this via sudo

You can replace the last step by a one-time setting of environment variables in your shell script. Or you can run the python/install.py script directly to give you more control over where the two relevant files are installed. See doc/Section_python.html for details.

You should then be able to launch Python and instantiate an instance of LAMMPS:

% python

from lammps import lammps lmp = lammps()

If that gives no errors, you have succesfully wrapped LAMMPS with Python. See doc/Section_python.html#py_7 for tests you can then use to run LAMMPS both in serial or parallel thru Python.

Note that you can also invoke Python code from within a LAMMPS input script, using the "python" command. See the doc/python.html doc page for details. The Python code you invoke can also call back to LAMMPS using the same interface described here for wrapping LAMMPS.

Alternative Python wrapper for LAMMPS

In addition to the original wrapper, you can use the PyLammps or IPyLammps wrappers to create simpler Python scripts and IPython notebooks.

from lammps import lammps, PyLammps, IPyLammps lmp = lammps() L = PyLammps(lmp)

Using these higher-level wrappers translates any function call into their corresponding LAMMPS command. Arguments are either passed as one string or individual parameters. Parameter lists are automatically joined to one command string. E.g.,

L.velocity("all create", 1.44, 87287, "loop geom")

is translated into the following call in the original interface:

lmp.command("velocity all create 1.44 87287 loop geom")

It also gives you an easier way to query the system state, evaluate variable expressions and access atom data. See examples/ipython/interface_usage.ipynb for more details.

Once you have successfully wrapped LAMMPS, you can run the Python scripts in the examples sub-directory:

trivial.py read/run a LAMMPS input script thru Python demo.py invoke various LAMMPS library interface routines simple.py parallel example, mimicing examples/COUPLE/simple/simple.cpp split.py parallel example mc.py Monte Carlo energy relaxation wrapper on LAMMPS gui.py GUI go/stop/temperature-slider to control LAMMPS plot.py real-time temeperature plot with GnuPlot via Pizza.py viz_tool.py real-time viz via some viz package vizplotgui_tool.py combination of viz.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", depending on what visualization package you have installed. We hope to add a VMD option soon.

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:

http://www.sandia.gov/~sjplimp/pizza.html

Note that for AtomEye, you need version 3, and their is a line in the scripts that specifies the path and name of the executable. See the AtomEye WWW pages for more details:

http://mt.seas.upenn.edu/Archive/Graphics/A http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html

The latter link is to AtomEye 3 which has the scriping 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 for more details:

http://www.pymol.org http://sourceforge.net/scm/?type=svn&group_id=4546

The latter link is to the open-source version.

Each example script has more documentation in the file that explains how to use it and what it is doing.

You can run a particular script in either of the following ways:

% trivial.py in.trivial % python -i trivial.py in.trivial

The former assumes that you have changed the first line of the script to point to the Python installed on your box and made the script exectable (e.g. chmod +x trivial.py).

The example scripts take the following arguments. The in.* args are LAMPS input scripts.

trivial.py in.trivial demo.py simple.py in.simple # can run in parallel (see below) split.py in.simple # can run in parallel (see below)

gui.py in.gui 100 plot.py in.plot 10 1000 thermo_temp viz_tool.py in.viz 100 5000 vizplotgui_tool.py in.viz 100 thermo_temp

To run LAMMPS in parallel from Python, so something like this:

% mpirun -np 4 simple.py in.simple % mpirun -np 4 python split.py in.simple

If you run simple.py as-is, this will invoke P instances of a one-processor run, where both Python and LAMMPS will run on single processors. Each running job will read the same input file, and write to same log.lammps file, which isn't too useful.

However, if you have either the Pypar or mpi4py packages installed in your Python, and uncomment the Pypar or mpi4py code in simple.py, then the above commands will invoke 1 instance of a P-processor run. Both Python and LAMMPS will run on P processors. The job will read the input file and write a single log.lammps file.

The split.py script can also be run in parallel. It uses mpi4py version 2.0.0 (or later), which makes it possible to pass a communicator when creating the LAMMPS object and thus run multiple instances of LAMMPS at the same time, each on a different subset of MPI ranks. Or run LAMMPS on one subset and some other program on the rest of the MPI ranks, concurrently. See comments in the split.py script for more details.