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

Details on the Python interface to LIGGGHTS and how to build LIGGGHTS 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 makeshlib                # creates Makefile.shlib
% make -f Makefile.shlib g++    # build for whatever machine target you wish
% make install-python           # may need to do this via sudo

You can replace the last step with running the python/install.py
script directly to give you more control over where two relevant files
are installed, or by setting environment variables in your shell
script.  See doc/Section_python.html for details.

You can then launch Python and instantiate an instance of LIGGGHTS:

% python
>>> from liggghts import liggghts
>>> lmp = liggghts()

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

-------------------------------------------------------------------

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

trivial.py          read/run a LIGGGHTS input script thru Python
demo.py	  	    invoke various LIGGGHTS library interface routines
simple.py	    mimic operation of couple/simple/simple.cpp in Python
gui.py		    GUI go/stop/temperature-slider to control LIGGGHTS
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.

-------------------------------------------------------------------

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.

Run the Python scripts with the following LIGGGHTS input scripts and
arguments:

trivial.py in.trivial
demo.py
simple.py in.simple
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

You can un-comment the Pypar calls if you want to run these in
parallel.  Then, for example, you can type:

% mpirun -np 4 trivial.py in.trivial
% mpirun -np 4 python trivial.py in.trivial

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