extract_fix(), and extract_variable() methods return values or
pointers to data structures internal to LAMMPS.
</P>
<P>For extract_global() see the src/library.cpp file for the list of
valid names. New names could easily be added. A double or integer is
returned. You need to specify the appropriate data type via the type
argument.
</P>
<P>For extract_atom(), a pointer to internal LAMMPS atom-based data is
returned, which you can use via normal Python subscripting. See the
extract() method in the src/atom.cpp file for a list of valid names.
Again, new names could easily be added. A pointer to a vector of
doubles or integers, or a pointer to an array of doubles (double **)
is returned. You need to specify the appropriate data type via the
type argument.
</P>
<P>For extract_compute() and extract_fix(), the global, per-atom, or
local data calulated by the compute or fix can be accessed. What is
returned depends on whether the compute or fix calculates a scalar or
vector or array. For a scalar, a single double value is returned. If
the compute or fix calculates a vector or array, a pointer to the
internal LAMMPS data is returned, which you can use via normal Python
subscripting. The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices. The I,J arguments can be left out if not needed.
See <A HREF = "Section_howto.html#howto_15">Section_howto 15</A> of the manual for a
discussion of global, per-atom, and local data, and of scalar, vector,
and array data types. See the doc pages for individual
<A HREF = "compute.html">computes</A> and <A HREF = "fix.html">fixes</A> for a description of what
they calculate and store.
</P>
<P>For extract_variable(), an <A HREF = "variable.html">equal-style or atom-style
variable</A> is evaluated and its result returned.
</P>
<P>For equal-style variables a single double value is returned and the
group argument is ignored. For atom-style variables, a vector of
doubles is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.
</P>
<P>The get_natoms() method returns the total number of atoms in the
simulation, as an int. Note that extract_global("natoms") returns the
same value, but as a double, which is the way LAMMPS stores it to
allow for systems with more atoms than can be stored in an int (> 2
billion).
</P>
<P>The get_coords() method returns an ctypes vector of doubles of length
3*natoms, for the coordinates of all the atoms in the simulation,
ordered by x,y,z and then by atom ID (see code for put_coords()
below). The array can be used via normal Python subscripting. If
atom IDs are not consecutively ordered within LAMMPS, a None is
returned as indication of an error.
</P>
<P>Note that the data structure get_coords() returns is different from
the data structure returned by extract_atom("x") in four ways. (1)
Get_coords() returns a vector which you index as x[i];
extract_atom() returns an array which you index as x[i][j]. (2)
Get_coords() orders the atoms by atom ID while extract_atom() does
not. (3) Get_coords() returns a list of all atoms in the simulation;
extract_atoms() returns just the atoms local to each processor. (4)
Finally, the get_coords() data structure is a copy of the atom coords
stored internally in LAMMPS, whereas extract_atom returns an array
that points directly to the internal data. This means you can change
values inside LAMMPS from Python by assigning a new values to the
extract_atom() array. To do this with the get_atoms() vector, you
need to change values in the vector, then invoke the put_coords()
method.
</P>
<P>The put_coords() method takes a vector of coordinates for all atoms in
the simulation, assumed to be ordered by x,y,z and then by atom ID,
and uses the values to overwrite the corresponding coordinates for
each atom inside LAMMPS. This requires LAMMPS to have its "map"
option enabled; see the <A HREF = "atom_modify.html">atom_modify</A> command for
details. If it is not or if atom IDs are not consecutively ordered,
no coordinates are reset,
</P>
<P>The array of coordinates passed to put_coords() must be a ctypes
vector of doubles, allocated and initialized something like this:
</P>
<PRE>from ctypes import *
natoms = lmp.get_atoms()
n3 = 3*natoms
x = (c_double*n3)()
x<B>0</B> = x coord of atom with ID 1
x<B>1</B> = y coord of atom with ID 1
x<B>2</B> = z coord of atom with ID 1
x<B>3</B> = x coord of atom with ID 2
...
x<B>n3-1</B> = z coord of atom with ID natoms
lmp.put_coords(x)
</PRE>
<P>Alternatively, you can just change values in the vector returned by
get_coords(), since it is a ctypes vector of doubles.
</P>
<HR>
<P>As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in src/library.cpp and
library.h. This means you can extend the Python wrapper via the
following steps:
</P>
<UL><LI>Add a new interface function to src/library.cpp and
src/library.h.
<LI>Rebuild LAMMPS as a shared library.
<LI>Add a wrapper method to python/lammps.py for this interface
function.
<LI>You should now be able to invoke the new interface function from a
Python script. Isn't ctypes amazing?
</UL>
<HR>
<HR>
<A NAME = "py_6"></A><H4>11.6 Example Python scripts that use LAMMPS
</H4>
<P>These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of
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.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >trivial.py</TD><TD > read/run a LAMMPS input script thru Python</TD></TR>
<TR><TD >demo.py</TD><TD > invoke various LAMMPS library interface routines</TD></TR>
<TR><TD >simple.py</TD><TD > mimic operation of couple/simple/simple.cpp in Python</TD></TR>
<TR><TD >gui.py</TD><TD > GUI go/stop/temperature-slider to control LAMMPS</TD></TR>
<TR><TD >plot.py</TD><TD > real-time temeperature plot with GnuPlot via Pizza.py</TD></TR>
<TR><TD >viz_tool.py</TD><TD > real-time viz via some viz package</TD></TR>
<TR><TD >vizplotgui_tool.py</TD><TD > combination of viz_tool.py and plot.py and gui.py
</TD></TR></TABLE></DIV>
<HR>
<P>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.
</P>
<P>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 <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py doc
pages</A> for more info:
</P>
<P>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 <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">here</A> or <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html">here</A> for more details: