README
1This directory contains Python code which wraps LAMMPS as a library
2and allows the LAMMPS library interface to be invoked from Python,
3either from a Python script or using Python interactively.
4
5Details on the Python interface to LAMMPS and how to build LAMMPS as a
6shared library, for use with Python, are given in
7doc/Section_python.html and in doc/Section_start.html#start_5.
8
9Basically you need to follow these steps in the src directory:
10
11% make g++ mode=shlib # build for whatever machine target you wish
12% make install-python # install into site-packages folder
13
14You can replace the last step by a one-time setting of environment
15variables in your shell script. Or you can run the python/install.py
16script directly to give you more control over where the two relevant
17files are installed. See doc/Python_install.html for details.
18
19You should then be able to launch Python and instantiate an instance
20of LAMMPS:
21
22% python
23>>> from lammps import lammps
24>>> lmp = lammps()
25
26If that gives no errors, you have successfully wrapped LAMMPS with
27Python. See doc/Section_python.html#py_7 for tests you can then use
28to run LAMMPS both in serial or parallel thru Python.
29
30Note that you can also invoke Python code from within a LAMMPS input
31script, using the "python" command. See the doc/python.html doc page
32for details. The Python code you invoke can also call back to LAMMPS
33using the same interface described here for wrapping LAMMPS.
34
35-------------------------------------------------------------------
36
37Once you have successfully wrapped LAMMPS, you can run the Python
38scripts in the examples sub-directory:
39
40trivial.py read/run a LAMMPS input script thru Python
41demo.py invoke various LAMMPS library interface routines
42simple.py parallel example, mimicing examples/COUPLE/simple/simple.cpp
43split.py parallel example
44mc.py Monte Carlo energy relaxation wrapper on LAMMPS
45gui.py GUI go/stop/temperature-slider to control LAMMPS
46plot.py real-time temperature plot with GnuPlot via Pizza.py
47matplotlib_plot.py real-time temperature plot with Matplotlib via Pizza.py
48viz_tool.py real-time viz via some viz package
49vizplotgui_tool.py combination of viz.py and plot.py and gui.py
50
51For the viz_tool.py and vizplotgui_tool.py commands, replace "tool"
52with "gl" or "atomeye" or "pymol", depending on what visualization
53package you have installed. We hope to add a VMD option soon.
54
55Note that for GL, you need to be able to run the Pizza.py GL tool,
56which is included in the pizza sub-directory. See the Pizza.py doc
57pages for more info:
58
59http://www.sandia.gov/~sjplimp/pizza.html
60
61Note that for AtomEye, you need version 3, and their is a line in the
62scripts that specifies the path and name of the executable. See
63the AtomEye WWW pages for more details:
64
65http://mt.seas.upenn.edu/Archive/Graphics/A
66http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html
67
68The latter link is to AtomEye 3 which has the scriping
69capability needed by these Python scripts.
70
71Note that for PyMol, you need to have built and installed the
72open-source version of PyMol in your Python, so that you can import it
73from a Python script. See the PyMol WWW pages for more details:
74
75http://www.pymol.org
76http://sourceforge.net/scm/?type=svn&group_id=4546
77
78The latter link is to the open-source version.
79
80-------------------------------------------------------------------
81
82Each example script has more documentation in the file that explains
83how to use it and what it is doing.
84
85You can run a particular script in either of the following ways:
86
87% trivial.py in.trivial
88% python -i trivial.py in.trivial
89
90The former assumes that you have changed the first line of the script
91to point to the Python installed on your box and made the script
92exectable (e.g. chmod +x trivial.py).
93
94The example scripts take the following arguments. The in.* args are
95LAMPS input scripts.
96
97trivial.py in.trivial
98demo.py
99simple.py in.simple # can run in parallel (see below)
100split.py in.simple # can run in parallel (see below)
101
102gui.py in.gui 100
103plot.py in.plot 10 1000 thermo_temp
104matplotlib_plot.py in.plot 10 1000 thermo_temp
105viz_tool.py in.viz 100 5000
106vizplotgui_tool.py in.viz 100 thermo_temp
107
108To run LAMMPS in parallel from Python, so something like this:
109
110% mpirun -np P simple.py in.simple
111% mpirun -np P python split.py in.simple
112
113If you run simple.py as-is, this will invoke P instances of a
114one-processor run, where both Python and LAMMPS will run on single
115processors. Each running job will read the same input file, and write
116to same log.lammps file, which isn't too useful.
117
118However, if you have the mpi4py Python package installed and uncomment mpi4py
119code in simple.py, then the above commands will invoke 1 instance of a
120P-processor run. Both Python and LAMMPS will run on P processors. The job will
121read the input file and write a single log.lammps file.
122
123The split.py script can also be run in parallel. It uses mpi4py
124version 2.0.0 (or later), which makes it possible to pass a
125communicator when creating the LAMMPS object and thus run multiple
126instances of LAMMPS at the same time, each on a different subset of
127MPI ranks. Or run LAMMPS on one subset and some other program on the
128rest of the MPI ranks, concurrently. See comments in the split.py
129script for more details.
130
131
132