jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@5200 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2010-11-02 15:05:51 +00:00
parent 88e0594987
commit b63b44e274
18 changed files with 1576 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
doc/Manual.html
View File

@ -157,6 +157,8 @@ listed above.
4.17 <A HREF = "Section_howto.html#4_17">Walls</A>
<BR>
4.18 <A HREF = "Section_howto.html#4_18">Elastic constants</A>
<BR>
4.19 <A HREF = "Section_howto.html#4_19">Library interface to LAMMPS</A>
<BR></UL>
<LI><A HREF = "Section_example.html">Example problems</A>
@ -166,19 +168,35 @@ listed above.
<LI><A HREF = "Section_modify.html">Modifying & Extending LAMMPS</A>
<LI><A HREF = "Section_python.html">Python interface</A>
<UL> 9.1 <A HREF = "Section_python.html#9_1">Extending Python with a serial version of LAMMPS</A>
<BR>
9.2 <A HREF = "Section_python.html#9_2">Creating a shared MPI library</A>
<BR>
9.3 <A HREF = "Section_python.html#9_3">Extending Python with a parallel version of LAMMPS</A>
<BR>
9.4 <A HREF = "Section_python.html#9_4">Extending Python with MPI</A>
<BR>
9.5 <A HREF = "Section_python.html#9_5">Testing the Python-LAMMPS interface</A>
<BR>
9.6 <A HREF = "Section_python.html#9_6">Using LAMMPS from Python</A>
<BR>
9.7 <A HREF = "Section_python.html#9_7">Example Python scripts that use LAMMPS</A>
<BR></UL>
<LI><A HREF = "Section_errors.html">Errors</A>
<UL> 9.1 <A HREF = "Section_errors.html#9_1">Common problems</A>
<UL> 10.1 <A HREF = "Section_errors.html#10_1">Common problems</A>
<BR>
9.2 <A HREF = "Section_errors.html#9_2">Reporting bugs</A>
10.2 <A HREF = "Section_errors.html#10_2">Reporting bugs</A>
<BR>
9.3 <A HREF = "Section_errors.html#9_3">Error & warning messages</A>
10.3 <A HREF = "Section_errors.html#10_3">Error & warning messages</A>
<BR></UL>
<LI><A HREF = "Section_history.html">Future and history</A>
<UL> 10.1 <A HREF = "Section_history.html#10_1">Coming attractions</A>
<UL> 11.1 <A HREF = "Section_history.html#11_1">Coming attractions</A>
<BR>
10.2 <A HREF = "Section_history.html#10_2">Past versions</A>
11.2 <A HREF = "Section_history.html#11_2">Past versions</A>
<BR></UL>
</OL>
@ -249,6 +267,22 @@ listed above.

40
doc/Manual.txt
View File

@ -112,18 +112,27 @@ listed above.
4.15 "Output from LAMMPS (thermo, dumps, computes, fixes, variables)"_4_15 :b
4.16 "Thermostatting, barostatting, and compute temperature"_4_16 :b
4.17 "Walls"_4_17 :b
4.18 "Elastic constants"_4_18 :ule,b
4.18 "Elastic constants"_4_18 :b
4.19 "Library interface to LAMMPS"_4_19 :ule,b
"Example problems"_Section_example.html :l
"Performance & scalability"_Section_perf.html :l
"Additional tools"_Section_tools.html :l
"Modifying & Extending LAMMPS"_Section_modify.html :l
"Python interface"_Section_python.html :l
9.1 "Extending Python with a serial version of LAMMPS"_9_1 :ulb,b
9.2 "Creating a shared MPI library"_9_2 :b
9.3 "Extending Python with a parallel version of LAMMPS"_9_3 :b
9.4 "Extending Python with MPI"_9_4 :b
9.5 "Testing the Python-LAMMPS interface"_9_5 :b
9.6 "Using LAMMPS from Python"_9_6 :b
9.7 "Example Python scripts that use LAMMPS"_9_7 :ule,b
"Errors"_Section_errors.html :l
9.1 "Common problems"_9_1 :ulb,b
9.2 "Reporting bugs"_9_2 :b
9.3 "Error & warning messages"_9_3 :ule,b
10.1 "Common problems"_10_1 :ulb,b
10.2 "Reporting bugs"_10_2 :b
10.3 "Error & warning messages"_10_3 :ule,b
"Future and history"_Section_history.html :l
10.1 "Coming attractions"_10_1 :ulb,b
10.2 "Past versions"_10_2 :ule,b
11.1 "Coming attractions"_11_1 :ulb,b
11.2 "Past versions"_11_2 :ule,b
:ole
:link(1_1,Section_intro.html#1_1)
@ -166,12 +175,21 @@ listed above.
:link(4_16,Section_howto.html#4_16)
:link(4_17,Section_howto.html#4_17)
:link(4_18,Section_howto.html#4_18)
:link(4_19,Section_howto.html#4_19)
:link(9_1,Section_errors.html#9_1)
:link(9_2,Section_errors.html#9_2)
:link(9_3,Section_errors.html#9_3)
:link(9_1,Section_python.html#9_1)
:link(9_2,Section_python.html#9_2)
:link(9_3,Section_python.html#9_3)
:link(9_4,Section_python.html#9_4)
:link(9_5,Section_python.html#9_5)
:link(9_6,Section_python.html#9_6)
:link(9_7,Section_python.html#9_7)
:link(10_1,Section_history.html#10_1)
:link(10_2,Section_history.html#10_2)
:link(10_1,Section_errors.html#10_1)
:link(10_2,Section_errors.html#10_2)
:link(10_3,Section_errors.html#10_3)
:link(11_1,Section_history.html#11_1)
:link(11_2,Section_history.html#11_2)
</BODY>

18
doc/Section_errors.html
View File

@ -1,5 +1,5 @@
<HTML>
<CENTER><A HREF = "Section_modify.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> -
<CENTER><A HREF = "Section_python.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> -
<A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_history.html">Next
Section</A>
</CENTER>
@ -11,18 +11,18 @@ Section</A>
<HR>
<H3>9. Errors
<H3>10. Errors
</H3>
<P>This section describes the various kinds of errors you can encounter
when using LAMMPS.
</P>
9.1 <A HREF = "#9_1">Common problems</A><BR>
9.2 <A HREF = "#9_2">Reporting bugs</A><BR>
9.3 <A HREF = "#9_3">Error & warning messages</A> <BR>
10.1 <A HREF = "#10_1">Common problems</A><BR>
10.2 <A HREF = "#10_2">Reporting bugs</A><BR>
10.3 <A HREF = "#10_3">Error & warning messages</A> <BR>
<HR>
<A NAME = "9_1"></A><H4>9.1 Common problems
<A NAME = "10_1"></A><H4>10.1 Common problems
</H4>
<P>If two LAMMPS runs do not produce the same answer on different
machines or different numbers of processors, this is typically not a
@ -81,7 +81,7 @@ decide if the WARNING is important or not. A WARNING message that is
generated in the middle of a run is only printed to the screen, not to
the logfile, to avoid cluttering up thermodynamic output. If LAMMPS
crashes or hangs without spitting out an error message first then it
could be a bug (see <A HREF = "#9_2">this section</A>) or one of the following
could be a bug (see <A HREF = "#10_2">this section</A>) or one of the following
cases:
</P>
<P>LAMMPS runs in the available memory a processor allows to be
@ -112,7 +112,7 @@ buffering or boost the sizes of messages that can be buffered.
</P>
<HR>
<A NAME = "9_2"></A><H4>9.2 Reporting bugs
<A NAME = "10_2"></A><H4>10.2 Reporting bugs
</H4>
<P>If you are confident that you have found a bug in LAMMPS, follow these
steps.
@ -142,7 +142,7 @@ causing the problem.
</P>
<HR>
<H4><A NAME = "9_3"></A>9.3 Error & warning messages
<H4><A NAME = "10_3"></A>10.3 Error & warning messages
</H4>
<P>These are two alphabetic lists of the <A HREF = "#error">ERROR</A> and
<A HREF = "#warn">WARNING</A> messages LAMMPS prints out and the reason why. If the

18
doc/Section_errors.txt
View File

@ -1,4 +1,4 @@
"Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws -
"Previous Section"_Section_python.html - "LAMMPS WWW Site"_lws -
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Section_history.html :c
@ -8,18 +8,18 @@ Section"_Section_history.html :c
:line
9. Errors :h3
10. Errors :h3
This section describes the various kinds of errors you can encounter
when using LAMMPS.
9.1 "Common problems"_#9_1
9.2 "Reporting bugs"_#9_2
9.3 "Error & warning messages"_#9_3 :all(b)
10.1 "Common problems"_#10_1
10.2 "Reporting bugs"_#10_2
10.3 "Error & warning messages"_#10_3 :all(b)
:line
9.1 Common problems :link(9_1),h4
10.1 Common problems :link(10_1),h4
If two LAMMPS runs do not produce the same answer on different
machines or different numbers of processors, this is typically not a
@ -78,7 +78,7 @@ decide if the WARNING is important or not. A WARNING message that is
generated in the middle of a run is only printed to the screen, not to
the logfile, to avoid cluttering up thermodynamic output. If LAMMPS
crashes or hangs without spitting out an error message first then it
could be a bug (see "this section"_#9_2) or one of the following
could be a bug (see "this section"_#10_2) or one of the following
cases:
LAMMPS runs in the available memory a processor allows to be
@ -109,7 +109,7 @@ buffering or boost the sizes of messages that can be buffered.
:line
9.2 Reporting bugs :link(9_2),h4
10.2 Reporting bugs :link(10_2),h4
If you are confident that you have found a bug in LAMMPS, follow these
steps.
@ -139,7 +139,7 @@ As a last resort, you can send an email directly to the
:line
9.3 Error & warning messages :h4,link(9_3)
10.3 Error & warning messages :h4,link(10_3)
These are two alphabetic lists of the "ERROR"_#error and
"WARNING"_#warn messages LAMMPS prints out and the reason why. If the

10
doc/Section_history.html
View File

@ -9,18 +9,18 @@
<HR>
<H3>10. Future and history
<H3>11. Future and history
</H3>
<P>This section lists features we are planning to add to LAMMPS, features
of previous versions of LAMMPS, and features of other parallel
molecular dynamics codes I've distributed.
</P>
10.1 <A HREF = "#10_1">Coming attractions</A><BR>
10.2 <A HREF = "#10_2">Past versions</A> <BR>
11.1 <A HREF = "#11_1">Coming attractions</A><BR>
11.2 <A HREF = "#11_2">Past versions</A> <BR>
<HR>
<H4><A NAME = "10_1"></A>10.1 Coming attractions
<H4><A NAME = "11_1"></A>11.1 Coming attractions
</H4>
<P>The current version of LAMMPS incorporates nearly all the features
from previous parallel MD codes developed at Sandia. These include
@ -49,7 +49,7 @@ page</A> on the LAMMPS WWW site for more details.
</UL>
<HR>
<H4><A NAME = "10_2"></A>10.2 Past versions
<H4><A NAME = "11_2"></A>11.2 Past versions
</H4>
<P>LAMMPS development began in the mid 1990s under a cooperative research
& development agreement (CRADA) between two DOE labs (Sandia and LLNL)

10
doc/Section_history.txt
View File

@ -6,18 +6,18 @@
:line
10. Future and history :h3
11. Future and history :h3
This section lists features we are planning to add to LAMMPS, features
of previous versions of LAMMPS, and features of other parallel
molecular dynamics codes I've distributed.
10.1 "Coming attractions"_#10_1
10.2 "Past versions"_#10_2 :all(b)
11.1 "Coming attractions"_#11_1
11.2 "Past versions"_#11_2 :all(b)
:line
10.1 Coming attractions :h4,link(10_1)
11.1 Coming attractions :h4,link(11_1)
The current version of LAMMPS incorporates nearly all the features
from previous parallel MD codes developed at Sandia. These include
@ -46,7 +46,7 @@ Direct Simulation Monte Carlo - DSMC :ul
:line
10.2 Past versions :h4,link(10_2)
11.2 Past versions :h4,link(11_2)
LAMMPS development began in the mid 1990s under a cooperative research
& development agreement (CRADA) between two DOE labs (Sandia and LLNL)

157
doc/Section_howto.html
View File

@ -11,8 +11,8 @@
<H3>4. How-to discussions
</H3>
<P>The following sections describe what commands can be used to perform
certain kinds of LAMMPS simulations.
<P>The following sections describe how to use various options within
LAMMPS.
</P>
4.1 <A HREF = "#4_1">Restarting a simulation</A><BR>
4.2 <A HREF = "#4_2">2d simulations</A><BR>
@ -31,11 +31,12 @@ certain kinds of LAMMPS simulations.
4.15 <A HREF = "#4_15">Output from LAMMPS (thermo, dumps, computes, fixes, variables)</A><BR>
4.16 <A HREF = "#4_16">Thermostatting, barostatting and computing temperature</A><BR>
4.17 <A HREF = "#4_17">Walls</A><BR>
4.18 <A HREF = "#4_18">Elastic constants</A> <BR>
4.18 <A HREF = "#4_18">Elastic constants</A><BR>
4.19 <A HREF = "#4_19">Library interface to LAMMPS</A> <BR>
<P>The example input scripts included in the LAMMPS distribution and
highlighted in <A HREF = "Section_example.html">this section</A> also show how to
setup and run various kinds of problems.
setup and run various kinds of simulations.
</P>
<HR>
@ -654,53 +655,31 @@ strain induced across grain boundaries
<P><A HREF = "Section_start.html#2_4">This section</A> of the documentation describes
how to build LAMMPS as a library. Once this is done, you can
interface with LAMMPS either via C++, C, or Fortran (or any other
language that supports a vanilla C-like interface, e.g. a scripting
language). For example, from C++ you could create one (or more)
"instances" of LAMMPS, pass it an input script to process, or execute
individual commands, all by invoking the correct class methods in
LAMMPS. From C or Fortran you can make function calls to do the same
things. Library.cpp and library.h contain such a C interface with the
functions:
interface with LAMMPS either via C++, C, Fortran, or Python (or any
other language that supports a vanilla C-like interface). For
example, from C++ you could create one (or more) "instances" of
LAMMPS, pass it an input script to process, or execute individual
commands, all by invoking the correct class methods in LAMMPS. From C
or Fortran you can make function calls to do the same things. See
<A HREF = "Section_python.html">this section</A> of the manual for a description of
the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface.
</P>
<PRE>void lammps_open(int, char **, MPI_Comm, void **);
void lammps_close(void *);
void lammps_file(void *, char *);
char *lammps_command(void *, char *);
</PRE>
<P>The functions contain C++ code you could write in a C++ application
that was invoking LAMMPS directly. Note that LAMMPS classes are
defined within a LAMMPS namespace (LAMMPS_NS) if you use them
from another C++ application.
<P>The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See <A HREF = "Section_howto.html#4_19">this section</A> of the manual
for a description of the interface and how to extend it for your
needs.
</P>
<P>Two of the routines in library.cpp are of particular note. The
lammps_open() function initiates LAMMPS and takes an MPI communicator
as an argument. It returns a pointer to a LAMMPS "object". As with
C++, the lammps_open() function can be called multiple times, to
create multiple instances of LAMMPS.
</P>
<P>LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate half the processors to LAMMPS and
half to the other code and run both codes simultaneously before
syncing them up periodically.
</P>
<P>Library.cpp contains a lammps_command() function to which the caller
passes a single LAMMPS command (a string). Thus the calling code can
read or generate a series of LAMMPS commands (e.g. an input script)
one line at a time and pass it thru the library interface to setup a
problem and then run it.
</P>
<P>A few other sample functions are included in library.cpp, but the key
idea is that you can write any functions you wish to define an
interface for how your code talks to LAMMPS and add them to
library.cpp and library.h. The routines you add can access any LAMMPS
data. The examples/couple directory has example C++ and C codes which
show how a stand-alone code can link LAMMPS as a library, run LAMMPS
on a subset of processors, grab data from LAMMPS, change it, and put
it back into LAMMPS.
<P>Note that the lammps_open() function that creates an instance of
LAMMPS takes an MPI communicator as an argument. This means that
instance of LAMMPS will run on the set of processors in the
communicator. Thus the calling code can run LAMMPS on all or a subset
of processors. For example, a wrapper script might decide to
alternate between LAMMPS and another code, allowing them both to run
on all the processors. Or it might allocate half the processors to
LAMMPS and half to the other code and run both codes simultaneously
before syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
</P>
<HR>
@ -1648,6 +1627,86 @@ converge and requires careful post-processing <A HREF = "#Shinoda">(Shinoda)</A>
</P>
<HR>
<A NAME = "4_19"></A><H4>4.19 Library interface to LAMMPS
</H4>
<P>As described in <A HREF = "Section_start.html#2_4">this section</A>, LAMMPS can be
built as a library, so that it can be called by another code, used in
a <A HREF = "Section_howto.html#4_10">coupled manner</A> with other codes, or driven
through a <A HREF = "Section_python.html">Python interface</A>.
</P>
<P>All of these methodologies use a C-style interface to LAMMPS that is
provided in the files src/library.cpp and src/library.h. The
functions therein have a C-style argument list, but contain C++ code
you could write yourself in a C++ application that was invoking LAMMPS
directly. The C++ code in the functions illustrates how to invoke
internal LAMMPS operations. Note that LAMMPS classes are defined
within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++
application.
</P>
<P>Library.cpp contains these 4 functions:
</P>
<PRE>void lammps_open(int, char **, MPI_Comm, void **);
void lammps_close(void *);
void lammps_file(void *, char *);
char *lammps_command(void *, char *);
</PRE>
<P>The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were <A HREF = "#2_6">command-line arguments</A> when
LAMMPS is run in stand-alone mode from the command line, and a MPI
communicator for LAMMPS to run under. It returns a ptr to the LAMMPS
object that is created, and which is used in subsequent library calls.
The lammps_open() function can be called multiple times, to create
multiple instances of LAMMPS.
</P>
<P>LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate half the processors to LAMMPS and
half to the other code and run both codes simultaneously before
syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
</P>
<P>The lammps_close() function is used to shut down an instance of LAMMPS
and free all its memory.
</P>
<P>The lammps_file() and lammps_command() functions are used to pass a
file or string to LAMMPS as if it were an input script or single
command in an input script. Thus the calling code can read or
generate a series of LAMMPS commands one line at a time and pass it
thru the library interface to setup a problem and then run it,
interleaving the lammps_command() calls with other calls to extract
information from LAMMPS, perform its own operations, or call another
code's library.
</P>
<P>Other useful functions are also included in library.cpp. For example:
</P>
<PRE>void *lammps_extract_global(void *, char *)
void *lammps_extract_atom(void *, char *)
void *lammps_extract_compute(void *, char *, int, int)
void *lammps_extract_fix(void *, char *, int, int, int, int)
void *lammps_extract_variable(void *, char *, char *)
int lammps_get_natoms(void *)
void lammps_get_coords(void *, double *)
void lammps_put_coords(void *, double *)
</PRE>
<P>These can extract various global or per-atom quantities from LAMMPS as
well as values calculated by a compute, fix, or variable. The "get"
and "put" operations can retrieve and reset atom coordinates.
See the library.cpp file and its associated header file library.h for
details.
</P>
<P>The key idea of the library interface is that you can write any
functions you wish to define how your code talks to LAMMPS and add
them to src/library.cpp and src/library.h, as well as to the <A HREF = "doc/Section_python.html">Python
interface</A>. The routines you add can access
or change any LAMMPS data you wish. The couple and python directories
have example C++ and C and Python codes which show how a driver code
can link to LAMMPS as a library, run LAMMPS on a subset of processors,
grab data from LAMMPS, change it, and put it back into LAMMPS.
</P>
<HR>
<HR>
<A NAME = "Berendsen"></A>

157
doc/Section_howto.txt
View File

@ -8,8 +8,8 @@
4. How-to discussions :h3
The following sections describe what commands can be used to perform
certain kinds of LAMMPS simulations.
The following sections describe how to use various options within
LAMMPS.
4.1 "Restarting a simulation"_#4_1
4.2 "2d simulations"_#4_2
@ -28,11 +28,12 @@ certain kinds of LAMMPS simulations.
4.15 "Output from LAMMPS (thermo, dumps, computes, fixes, variables)"_#4_15
4.16 "Thermostatting, barostatting and computing temperature"_#4_16
4.17 "Walls"_#4_17
4.18 "Elastic constants"_#4_18 :all(b)
4.18 "Elastic constants"_#4_18
4.19 "Library interface to LAMMPS"_#4_19 :all(b)
The example input scripts included in the LAMMPS distribution and
highlighted in "this section"_Section_example.html also show how to
setup and run various kinds of problems.
setup and run various kinds of simulations.
:line
@ -649,53 +650,31 @@ strain induced across grain boundaries :l,ule
"This section"_Section_start.html#2_4 of the documentation describes
how to build LAMMPS as a library. Once this is done, you can
interface with LAMMPS either via C++, C, or Fortran (or any other
language that supports a vanilla C-like interface, e.g. a scripting
language). For example, from C++ you could create one (or more)
"instances" of LAMMPS, pass it an input script to process, or execute
individual commands, all by invoking the correct class methods in
LAMMPS. From C or Fortran you can make function calls to do the same
things. Library.cpp and library.h contain such a C interface with the
functions:
interface with LAMMPS either via C++, C, Fortran, or Python (or any
other language that supports a vanilla C-like interface). For
example, from C++ you could create one (or more) "instances" of
LAMMPS, pass it an input script to process, or execute individual
commands, all by invoking the correct class methods in LAMMPS. From C
or Fortran you can make function calls to do the same things. See
"this section"_Section_python.html of the manual for a description of
the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface.
void lammps_open(int, char **, MPI_Comm, void **);
void lammps_close(void *);
void lammps_file(void *, char *);
char *lammps_command(void *, char *); :pre
The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See "this section"_Section_howto.html#4_19 of the manual
for a description of the interface and how to extend it for your
needs.
The functions contain C++ code you could write in a C++ application
that was invoking LAMMPS directly. Note that LAMMPS classes are
defined within a LAMMPS namespace (LAMMPS_NS) if you use them
from another C++ application.
Two of the routines in library.cpp are of particular note. The
lammps_open() function initiates LAMMPS and takes an MPI communicator
as an argument. It returns a pointer to a LAMMPS "object". As with
C++, the lammps_open() function can be called multiple times, to
create multiple instances of LAMMPS.
LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate half the processors to LAMMPS and
half to the other code and run both codes simultaneously before
syncing them up periodically.
Library.cpp contains a lammps_command() function to which the caller
passes a single LAMMPS command (a string). Thus the calling code can
read or generate a series of LAMMPS commands (e.g. an input script)
one line at a time and pass it thru the library interface to setup a
problem and then run it.
A few other sample functions are included in library.cpp, but the key
idea is that you can write any functions you wish to define an
interface for how your code talks to LAMMPS and add them to
library.cpp and library.h. The routines you add can access any LAMMPS
data. The examples/couple directory has example C++ and C codes which
show how a stand-alone code can link LAMMPS as a library, run LAMMPS
on a subset of processors, grab data from LAMMPS, change it, and put
it back into LAMMPS.
Note that the lammps_open() function that creates an instance of
LAMMPS takes an MPI communicator as an argument. This means that
instance of LAMMPS will run on the set of processors in the
communicator. Thus the calling code can run LAMMPS on all or a subset
of processors. For example, a wrapper script might decide to
alternate between LAMMPS and another code, allowing them both to run
on all the processors. Or it might allocate half the processors to
LAMMPS and half to the other code and run both codes simultaneously
before syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
:line
@ -1634,6 +1613,86 @@ tensor. Another approach is to sample the triclinic cell fluctuations
that occur in an NPT simulation. This method can also be slow to
converge and requires careful post-processing "(Shinoda)"_#Shinoda
:line
4.19 Library interface to LAMMPS :link(4_19),h4
As described in "this section"_Section_start.html#2_4, LAMMPS can be
built as a library, so that it can be called by another code, used in
a "coupled manner"_Section_howto.html#4_10 with other codes, or driven
through a "Python interface"_Section_python.html.
All of these methodologies use a C-style interface to LAMMPS that is
provided in the files src/library.cpp and src/library.h. The
functions therein have a C-style argument list, but contain C++ code
you could write yourself in a C++ application that was invoking LAMMPS
directly. The C++ code in the functions illustrates how to invoke
internal LAMMPS operations. Note that LAMMPS classes are defined
within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++
application.
Library.cpp contains these 4 functions:
void lammps_open(int, char **, MPI_Comm, void **);
void lammps_close(void *);
void lammps_file(void *, char *);
char *lammps_command(void *, char *); :pre
The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were "command-line arguments"_#2_6 when
LAMMPS is run in stand-alone mode from the command line, and a MPI
communicator for LAMMPS to run under. It returns a ptr to the LAMMPS
object that is created, and which is used in subsequent library calls.
The lammps_open() function can be called multiple times, to create
multiple instances of LAMMPS.
LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate half the processors to LAMMPS and
half to the other code and run both codes simultaneously before
syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
The lammps_close() function is used to shut down an instance of LAMMPS
and free all its memory.
The lammps_file() and lammps_command() functions are used to pass a
file or string to LAMMPS as if it were an input script or single
command in an input script. Thus the calling code can read or
generate a series of LAMMPS commands one line at a time and pass it
thru the library interface to setup a problem and then run it,
interleaving the lammps_command() calls with other calls to extract
information from LAMMPS, perform its own operations, or call another
code's library.
Other useful functions are also included in library.cpp. For example:
void *lammps_extract_global(void *, char *)
void *lammps_extract_atom(void *, char *)
void *lammps_extract_compute(void *, char *, int, int)
void *lammps_extract_fix(void *, char *, int, int, int, int)
void *lammps_extract_variable(void *, char *, char *)
int lammps_get_natoms(void *)
void lammps_get_coords(void *, double *)
void lammps_put_coords(void *, double *) :pre
These can extract various global or per-atom quantities from LAMMPS as
well as values calculated by a compute, fix, or variable. The "get"
and "put" operations can retrieve and reset atom coordinates.
See the library.cpp file and its associated header file library.h for
details.
The key idea of the library interface is that you can write any
functions you wish to define how your code talks to LAMMPS and add
them to src/library.cpp and src/library.h, as well as to the "Python
interface"_doc/Section_python.html. The routines you add can access
or change any LAMMPS data you wish. The couple and python directories
have example C++ and C and Python codes which show how a driver code
can link to LAMMPS as a library, run LAMMPS on a subset of processors,
grab data from LAMMPS, change it, and put it back into LAMMPS.
:line
:line

2
doc/Section_intro.html
View File

@ -413,7 +413,7 @@ Site</A>, or have a suggestion for something to clarify or include,
send an email to the
<A HREF = "http://lammps.sandia.gov/authors.html">developers</A>.
<LI>If you find a bug, <A HREF = "Section_errors.html#9_2">this section</A> describes
<LI>If you find a bug, <A HREF = "Section_errors.html#10_2">this section</A> describes
how to report it.
<LI>If you publish a paper using LAMMPS results, send the citation (and

2
doc/Section_intro.txt
View File

@ -403,7 +403,7 @@ Site"_lws, or have a suggestion for something to clarify or include,
send an email to the
"developers"_http://lammps.sandia.gov/authors.html. :l
If you find a bug, "this section"_Section_errors.html#9_2 describes
If you find a bug, "this section"_Section_errors.html#10_2 describes
how to report it. :l
If you publish a paper using LAMMPS results, send the citation (and

2
doc/Section_modify.html
View File

@ -1,6 +1,6 @@
<HTML>
<CENTER><A HREF = "Section_tools.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> -
<A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_errors.html">Next
<A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_python.html">Next
Section</A>
</CENTER>

2
doc/Section_modify.txt
View File

@ -1,6 +1,6 @@
"Previous Section"_Section_tools.html - "LAMMPS WWW Site"_lws -
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Section_errors.html :c
Section"_Section_python.html :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)

620
doc/Section_python.html Normal file
View File

@ -0,0 +1,620 @@
<HTML>
<CENTER><A HREF = "Section_modify.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_errors.html">Next Section</A>
</CENTER>
<HR>
<H3>9. Python interface to LAMMPS
</H3>
<P>The LAMMPS distribution includes some Python code in its python
directory which wraps the library interface to LAMMPS. This makes it
is possible to run LAMMPS, invoke LAMMPS commands or give it an input
script, extract LAMMPS results, an modify internal LAMMPS variables,
either from a Python script or interactively from a Python prompt.
</P>
<P><A HREF = "http://www.python.org">Python</A> is a powerful scripting and programming
language which can be used to wrap software like LAMMPS and other
packages. It can be used to glue multiple pieces of software
together, e.g. to run a coupled or multiscale model. See <A HREF = "Section_howto.html#4_10">this
section</A> of the manual and the couple
directory of the distribution for more ideas about coupling LAMMPS to
other codes. See <A HREF = "Section_start.html#2_4">this section</A> about how to
build LAMMPS as a library, and <A HREF = "Section_howto.html#4_19">this section</A>
for a description of the library interface provided in src/library.cpp
and src/library.h and how to extend it for your needs. As described
below, that interface is what is exposed to Python. It is designed to
be easy to add functions to. This has the effect of extending the
Python inteface as well. See details below.
</P>
<P>By using the Python interface LAMMPS can also be coupled with a GUI or
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.
</P>
<P>Two advantages of using Python are how concise the language is and
that it can be run interactively, enabling rapid development and
debugging of programs. If you use it to mostly invoke costly
operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.
</P>
<P>Before using LAMMPS from a Python script, the Python on your machine
must be "extended" to include an interface to the LAMMPS library. If
your Python script will invoke MPI operations, you will also need to
extend your Python with an interface to MPI itself.
</P>
<P>Thus you should first decide how you intend to use LAMMPS from Python.
There are 3 options:
</P>
<P>(1) Use LAMMPS on a single processor running Python.
</P>
<P>(2) Use LAMMPS in parallel, where each processor runs Python, but your
Python program does not use MPI.
</P>
<P>(3) Use LAMMPS in parallel, where each processor runs Python, and your
Python script also makes MPI calls through a Python/MPI interface.
</P>
<P>Note that for (2) and (3) you will not be able to use Python
interactively by typing commands and getting a response. This is
because you will have multiple instances of Python running (e.g. on a
parallel machine) and they cannot all read what you type.
</P>
<P>Working in mode (1) does not require your machine to have MPI
installed. You should extend your Python with a serial version of
LAMMPS and the dummy MPI library provided with LAMMPS. See
instructions below on how to do this.
</P>
<P>Working in mode (2) requires your machine to have an MPI library
installed, but your Python does not need to be extended with MPI
itself. The MPI library must be a shared library (e.g. a *.so file on
Linux) which is not typically created when MPI is built/installed.
See instruction below on how to do this. You should extend your
Python with the a parallel versionn of LAMMPS which will use the
shared MPI system library. See instructions below on how to do this.
</P>
<P>Working in mode (3) requires your machine to have MPI installed (as a
shared library as in (2)). You must also extend your Python with a
parallel version of LAMMPS (same as in (2)) and with MPI itself, via
one of several available Python/MPI packages. See instructions below
on how to do the latter task.
</P>
<P>Several of the following sub-sections cover the rest of the Python
setup discussion. The next to last sub-section describes the Python
syntax used to invoke LAMMPS. The last sub-section describes example
Python scripts included in the python directory.
</P>
<UL><LI><A HREF = "#9_1">Extending Python with a serial version of LAMMPS</A>
<LI><A HREF = "#9_2">Creating a shared MPI library</A>
<LI><A HREF = "#9_3">Extending Python with a parallel version of LAMMPS</A>
<LI><A HREF = "#9_4">Extending Python with MPI</A>
<LI><A HREF = "#9_5">Testing the Python-LAMMPS interface</A>
<LI><A HREF = "#9_6">Using LAMMPS from Python</A>
<LI><A HREF = "#9_7">Example Python scripts that use LAMMPS</A>
</UL>
<P>Before proceeding, there are 2 items to note.
</P>
<P>(1) The provided Python wrapper for LAMMPS uses the amazing and
magical (to me) "ctypes" package in Python, which auto-generates the
interface code needed between Python and a set of C interface routines
for a library. Ctypes is part of standard Python for versions 2.5 and
later. You can check which version of Python you have installed, by
simply typing "python" at a shell prompt.
</P>
<P>(2) Any library wrapped by Python, including LAMMPS, must be built as
a shared library (e.g. a *.so file on Linux and not a *.a file). The
python/setup_serial.py and setup.py scripts do this build for LAMMPS
itself (described below). But if you have LAMMPS configured to use
additional packages that have their own libraries, then those
libraries must also be shared libraries. E.g. MPI, FFTW, or any of
the libraries in lammps/lib. When you build LAMMPS as a stand-alone
code, you are not building shared versions of these libraries.
</P>
<P>The discussion below describes how to create a shared MPI library. I
suggest you start by configuing LAMMPS without packages installed that
require any libraries besides MPI. See <A HREF = "Section_start.html#2_3">this
section</A> of the manual for a discussion of
LAMMPS pacakges. E.g. do not use the KSPACE, GPU, MEAM, POEMS, or
REAX packages.
</P>
<P>If you are successfully follow the steps belwo to build the Python
wrappers and use this version of LAMMPS through Python, you can then
take the next step of adding LAMMPS packages that use additional
libraries. This will require you to build a shared library for that
package's library, similar to what is described below for MPI. It
will also require you to edit the python/setup_serial.py or setup.py
scripts to enable Python to access those libraries when it builds the
LAMMPS wrapper.
</P>
<HR>
<HR>
<A NAME = "9_1"></A><H4>Extending Python with a serial version of LAMMPS
</H4>
<P>From the python directory in the LAMMPS distribution, type
</P>
<PRE>python setup_serial.py build
</PRE>
<P>and then one of these commands:
</P>
<PRE>sudo python setup_serial.py install
python setup_serial.py install --home=~/foo
</PRE>
<P>The "build" command should compile all the needed LAMMPS files,
including its dummy MPI library. The first "install" command will put
the needed files in your Python's site-packages sub-directory, so that
Python can load them. For example, if you installed Python yourself
on a Linux machine, it would typically be somewhere like
/usr/local/lib/python2.5/site-packages. Installing Python packages
this way often requires you to be able to write to the Python
directories, which may require root priveleges, hence the "sudo"
prefix. If this is not the case, you can drop the "sudo".
</P>
<P>Alternatively, you can install the LAMMPS files (or any other Python
packages) in your own user space. The second "install" command does
this, where you should replace "foo" with your directory of choice.
</P>
<P>If these commands are successful, a <I>lammps.py</I> and
<I>_lammps_serial.so</I> file will be put in the appropriate directory.
</P>
<HR>
<A NAME = "9_2"></A><H4>Creating a shared MPI library
</H4>
<P>A shared library is one that is dynamically loadable, which is what
Python requires. On Linux this is a library file that ends in ".so",
not ".a". Such a shared library is normally not built if you
installed MPI yourself, but it is easy to do. Here is how to do it
for <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH</A>, a popular open-source version of MPI, distributed
by Argonne National Labs. From within the mpich directory, type
</P>
<PRE>./configure --enable-sharedlib=gcc
make
make install
</PRE>
<P>You may need to use "sudo make install" in place of the last line.
The end result should be the file libmpich.so in /usr/local/lib.
</P>
<P>IMPORTANT NOTE: If the file libmpich.a already exists in your
installation directory (e.g. /usr/local/lib), you will now have both a
static and shared MPI library. This will be fine for running LAMMPS
from Python since it only uses the shared library. But if you now try
to build LAMMPS by itself as a stand-alone program (cd lammps/src;
make foo) or build other codes that expect to link against libmpich.a,
then those builds will typically fail if the linker uses libmpich.so
instead. This means you will need to remove the file
/usr/local/lib/libmich.so before building LAMMPS again as a
stand-alone code.
</P>
<HR>
<A NAME = "9_3"></A><H4>Extending Python with a parallel version of LAMMPS
</H4>
<P>From the python directory, type
</P>
<PRE>python setup.py build
</PRE>
<P>and then one of these commands:
</P>
<PRE>sudo python setup.py install
python setup.py install --home=~/foo
</PRE>
<P>The "build" command should compile all the needed LAMMPS C++ files,
which will require MPI to be installed on your system. This means it
must find both the header file mpi.h and a shared library file,
e.g. libmpich.so if the MPICH version of MPI is installed. See the
preceding section for how to create a shared library version of MPI if
it does not exist. You may need to adjust the "include_dirs" and
"library_dirs" and "libraries" fields in python/setup.py to
insure the Python build finds all the files it needs.
</P>
<P>The first "install" command will put the needed files in your Python's
site-packages sub-directory, so that Python can load them. For
example, if you installed Python yourself on a Linux machine, it would
typically be somewhere like /usr/local/lib/python2.5/site-packages.
Installing Python packages this way often requires you to be able to
write to the Python directories, which may require root priveleges,
hence the "sudo" prefix. If this is not the case, you can drop the
"sudo".
</P>
<P>Alternatively, you can install the LAMMPS files (or any other Python
packages) in your own user space. The second "install" command does
this, where you should replace "foo" with your directory of choice.
</P>
<P>If these commands are successful, a <I>lammps.py</I> and <I>_lammps.so</I> file
will be put in the appropriate directory.
</P>
<HR>
<A NAME = "9_4"></A><H4>Extending Python with MPI
</H4>
<P>There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python.
</P>
<P>These include
</P>
<UL><LI><A HREF = "http://pympi.sourceforge.net/">pyMPI</A>
<LI><A HREF = "http://code.google.com/p/maroonmpi/">maroonmpi</A>
<LI><A HREF = "http://code.google.com/p/mpi4py/">mpi4py</A>
<LI><A HREF = "http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16">myMPI</A>
<LI><A HREF = "http://datamining.anu.edu.au/~ole/pypar">Pypar</A>
</UL>
<P>All of these except pyMPI work by wrapping the MPI library (which must
be available on your system as a shared library, as discussed above),
and exposing (some portion of) its interface to your Python script.
This means they cannot be used interactively in parallel, since they
do not address the issue of interactive input to multiple instances of
Python running on different processors. The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of python
itself) as a result.
</P>
<P>In principle any of these Python/MPI packages should work to invoke
both calls to LAMMPS and MPI itself from a Python script running in
parallel. However, when I downloaded and looked at a few of them,
their docuemtation was incomplete and I had trouble with their
installation. It's not clear if some of the packages are still being
actively developed and supported.
</P>
<P>The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous <A HREF = "http://numpy.scipy.org">Numpy
package</A> be installed in your Python. After
launching python, type
</P>
<PRE>>>> import numpy
</PRE>
<P>to see if it is installed. If not, here is how to install it (version
1.3.0b1 as of April 2009). Unpack the numpy tarball and from its
top-level directory, type
</P>
<PRE>python setup.py build
sudo python setup.py install
</PRE>
<P>The "sudo" is only needed if required to copy Numpy files into your
Python distribution's site-packages directory.
</P>
<P>To install Pypar (version pypar-2.1.0_66 as of April 2009), unpack it
and from its "source" directory, type
</P>
<PRE>python setup.py build
sudo python setup.py install
</PRE>
<P>Again, the "sudo" is only needed if required to copy PyPar files into
your Python distribution's site-packages directory.
</P>
<P>If you have successully installed Pypar, you should be able to run
python serially and type
</P>
<PRE>>>> import pypar
</PRE>
<P>without error. You should also be able to run python in parallel
on a simple test script
</P>
<PRE>% mpirun -np 4 python test.script
</PRE>
<P>where test.script contains the lines
</P>
<PRE>import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())
</PRE>
<P>and see one line of output for each processor you ran on.
</P>
<HR>
<A NAME = "9_5"></A><H4>Testing the Python-LAMMPS interface
</H4>
<P>Before using LAMMPS in a Python program, one more step is needed. The
interface to LAMMPS is via the Python ctypes package, which loads the
shared LAMMPS library via a CDLL() call, which in turn is a wrapper on
the C-library dlopen(). This command is different than a normal
Python "import" and needs to be able to find the LAMMPS shared
library, which is either in the Python site-packages directory or in a
local directory you specified in the "python setup.py install"
command, as described above.
</P>
<P>The simplest way to do this is add a line like this to your
.cshrc or other shell start-up file.
</P>
<PRE>setenv LD_LIBRARY_PATH
${LD_LIBRARY_PATH}:/usr/local/lib/python2.5/site-packages
</PRE>
<P>and then execute the shell file to insure the path has been updated.
This will extend the path that dlopen() uses to look for shared
libraries.
</P>
<P>To test if the serial LAMMPS library has been successfully installed
(mode 1 above), launch Python and type
</P>
<PRE>>>> from lammps import lammps
>>> lmp = lammps()
</PRE>
<P>If you get no errors, you're ready to use serial LAMMPS from Python.
</P>
<P>If you built LAMMPS for parallel use (mode 2 or 3 above), launch
Python in parallel:
</P>
<PRE>% mpirun -np 4 python test.script
</PRE>
<P>where test.script contains the lines
</P>
<PRE>import pypar
from lammps import lammps
lmp = lammps()
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()), lmp
pypar.finalize()
</PRE>
<P>Again, if you get no errors, you're good to go.
</P>
<P>Note that if you left out the "import pypar" line from this script,
you would instantiate and run LAMMPS independently on each of the P
processors specified in the mpirun command. You can test if Pypar is
enabling true parallel Python and LAMMPS by adding a line to the above
sequence of commands like lmp.file("in.lj") to run an input script and
see if the LAMMPS run says it ran on P processors or if you get output
from P duplicated 1-processor runs written to the screen. In the
latter case, Pypar is not working correctly.
</P>
<P>Note that this line:
</P>
<PRE>from lammps import lammps
</PRE>
<P>will import either the serial or parallel version of the LAMMPS
library, as wrapped by lammps.py. But if you installed both via
setup_serial.py and setup.py, it will always import the parallel
version, since it attempts that first.
</P>
<P>Note that if your Python script imports the Pypar package (as above),
so that it can use MPI calls directly, then Pypar initializes MPI for
you. Thus the last line of your Python script should be
pypar.finalize(), to insure MPI is shut down correctly.
</P>
<P>Also note that a Python script can be invoked in one of several ways:
</P>
<P>% python foo.script
% python -i foo.script
% foo.script
</P>
<P>The last command requires that the first line of the script be
something like this:
</P>
<P>#!/usr/local/bin/python
#!/usr/local/bin/python -i
</P>
<P>where the path points to where you have Python installed, and that you
have made the script file executable:
</P>
<P>% chmod +x foo.script
</P>
<P>Without the "-i" flag, Python will exit when the script finishes.
With the "-i" flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.
</P>
<HR>
<HR>
<A NAME = "9_6"></A><H4>Using LAMMPS from Python
</H4>
<P>The Python interface to LAMMPS consists of a Python "lammps" module,
the source code for which is in python/lammps.py, which creates a
"lammps" object, with a set of methods that can be invoked on that
object. The sample Python code below assumes you have first imported
the "lammps" module in your Python script and its settings as
follows:
</P>
<PRE>from lammps import lammps
from lammps import LMPINT as INT
from lammps import LMPDOUBLE as DOUBLE
from lammps import LMPIPTR as IPTR
from lammps import LMPDPTR as DPTR
from lammps import LMPDPTRPTR as DPTRPTR
</PRE>
<P>These are the methods defined by the lammps module. If you look
at the file src/library.cpp you will see that they correspond
one-to-one with calls you can make to the LAMMPS library from a C++ or
C or Fortran program.
</P>
<PRE>lmp = lammps() # create a LAMMPS object
lmp = lammps(list) # ditto, with command-line args, list = ["-echo","screen"]
</PRE>
<PRE>lmp.close() # destroy a LAMMPS object
</PRE>
<PRE>lmp.file(file) # run an entire input script, file = "in.lj"
lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100"
</PRE>
<PRE>xlo = lmp.extract_global(name,type) # extract a global quantity
# name = "boxxlo", "nlocal", etc
# type = INT or DOUBLE
</PRE>
<PRE>coords = lmp.extract_atom(name,type) # extract a per-atom quantity
# name = "x", "type", etc
# type = IPTR or DPTR or DPTRPTR
</PRE>
<PRE>eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute
v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix
# id = ID of compute or fix
# style = 0 = global data
# 1 = per-atom data
# 2 = local data
# type = 0 = scalar
# 1 = vector
# 2 = array
# i,j = indices of value in global vector or array
</PRE>
<PRE>var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable
# name = name of variable
# group = group ID (ignored for equal-style variables)
# flag = 0 = equal-style variable
# 1 = atom-style variable
</PRE>
<PRE>natoms = lmp.get_natoms() # total # of atoms as int
x = lmp.get_coords() # return coords of all atoms in x
lmp.put_coords(x) # set all atom coords via x
</PRE>
<HR>
<P>The creation of a LAMMPS object does not take an MPI communicator as
an argument. There should be a way to do this, so that the LAMMPS
instance runs on a subset of processors, if desired, but I don't yet
know how from Pypar. So for now, it runs on MPI_COMM_WORLD, which is
all the processors.
</P>
<P>The file() and command() methods allow an input script or single
commands to be invoked.
</P>
<P>The extract_global(), extract_atom(), extract_compute(),
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#4_15">this section</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>Verify the new function is syntactically correct by building LAMMPS as
a library - see <A HREF = "Section_start.html#2_4">this section</A> of the
manual.
<LI>Add a wrapper method in the Python LAMMPS module to python/lammps.py
for this interface function.
<LI>Rebuild the Python wrapper via python/setup_serial.py or
python/setup.py.
<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 = "9_7"></A><H4>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 via 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 <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A></TD></TR>
<TR><TD >viz.py</TD><TD > real-time viz from GL tool in <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A></TD></TR>
<TR><TD >vizplotgui.py</TD><TD > combination of viz.py and plot.py and gui.py
</TD></TR></TABLE></DIV>
<P>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.
</P>
</HTML>

610
doc/Section_python.txt Normal file
View File

@ -0,0 +1,610 @@
"Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_errors.html :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
9. Python interface to LAMMPS :h3
The LAMMPS distribution includes some Python code in its python
directory which wraps the library interface to LAMMPS. This makes it
is possible to run LAMMPS, invoke LAMMPS commands or give it an input
script, extract LAMMPS results, an modify internal LAMMPS variables,
either from a Python script or interactively from a Python prompt.
"Python"_http://www.python.org is a powerful scripting and programming
language which can be used to wrap software like LAMMPS and other
packages. It can be used to glue multiple pieces of software
together, e.g. to run a coupled or multiscale model. See "this
section"_Section_howto.html#4_10 of the manual and the couple
directory of the distribution for more ideas about coupling LAMMPS to
other codes. See "this section"_Section_start.html#2_4 about how to
build LAMMPS as a library, and "this section"_Section_howto.html#4_19
for a description of the library interface provided in src/library.cpp
and src/library.h and how to extend it for your needs. As described
below, that interface is what is exposed to Python. It is designed to
be easy to add functions to. This has the effect of extending the
Python inteface as well. See details below.
By using the Python interface LAMMPS can also be coupled with a GUI or
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.
Two advantages of using Python are how concise the language is and
that it can be run interactively, enabling rapid development and
debugging of programs. If you use it to mostly invoke costly
operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.
Before using LAMMPS from a Python script, the Python on your machine
must be "extended" to include an interface to the LAMMPS library. If
your Python script will invoke MPI operations, you will also need to
extend your Python with an interface to MPI itself.
Thus you should first decide how you intend to use LAMMPS from Python.
There are 3 options:
(1) Use LAMMPS on a single processor running Python.
(2) Use LAMMPS in parallel, where each processor runs Python, but your
Python program does not use MPI.
(3) Use LAMMPS in parallel, where each processor runs Python, and your
Python script also makes MPI calls through a Python/MPI interface.
Note that for (2) and (3) you will not be able to use Python
interactively by typing commands and getting a response. This is
because you will have multiple instances of Python running (e.g. on a
parallel machine) and they cannot all read what you type.
Working in mode (1) does not require your machine to have MPI
installed. You should extend your Python with a serial version of
LAMMPS and the dummy MPI library provided with LAMMPS. See
instructions below on how to do this.
Working in mode (2) requires your machine to have an MPI library
installed, but your Python does not need to be extended with MPI
itself. The MPI library must be a shared library (e.g. a *.so file on
Linux) which is not typically created when MPI is built/installed.
See instruction below on how to do this. You should extend your
Python with the a parallel versionn of LAMMPS which will use the
shared MPI system library. See instructions below on how to do this.
Working in mode (3) requires your machine to have MPI installed (as a
shared library as in (2)). You must also extend your Python with a
parallel version of LAMMPS (same as in (2)) and with MPI itself, via
one of several available Python/MPI packages. See instructions below
on how to do the latter task.
Several of the following sub-sections cover the rest of the Python
setup discussion. The next to last sub-section describes the Python
syntax used to invoke LAMMPS. The last sub-section describes example
Python scripts included in the python directory.
"Extending Python with a serial version of LAMMPS"_#9_1
"Creating a shared MPI library"_#9_2
"Extending Python with a parallel version of LAMMPS"_#9_3
"Extending Python with MPI"_#9_4
"Testing the Python-LAMMPS interface"_#9_5
"Using LAMMPS from Python"_#9_6
"Example Python scripts that use LAMMPS"_#9_7 :ul
Before proceeding, there are 2 items to note.
(1) The provided Python wrapper for LAMMPS uses the amazing and
magical (to me) "ctypes" package in Python, which auto-generates the
interface code needed between Python and a set of C interface routines
for a library. Ctypes is part of standard Python for versions 2.5 and
later. You can check which version of Python you have installed, by
simply typing "python" at a shell prompt.
(2) Any library wrapped by Python, including LAMMPS, must be built as
a shared library (e.g. a *.so file on Linux and not a *.a file). The
python/setup_serial.py and setup.py scripts do this build for LAMMPS
itself (described below). But if you have LAMMPS configured to use
additional packages that have their own libraries, then those
libraries must also be shared libraries. E.g. MPI, FFTW, or any of
the libraries in lammps/lib. When you build LAMMPS as a stand-alone
code, you are not building shared versions of these libraries.
The discussion below describes how to create a shared MPI library. I
suggest you start by configuing LAMMPS without packages installed that
require any libraries besides MPI. See "this
section"_Section_start.html#2_3 of the manual for a discussion of
LAMMPS pacakges. E.g. do not use the KSPACE, GPU, MEAM, POEMS, or
REAX packages.
If you are successfully follow the steps belwo to build the Python
wrappers and use this version of LAMMPS through Python, you can then
take the next step of adding LAMMPS packages that use additional
libraries. This will require you to build a shared library for that
package's library, similar to what is described below for MPI. It
will also require you to edit the python/setup_serial.py or setup.py
scripts to enable Python to access those libraries when it builds the
LAMMPS wrapper.
:line
:line
Extending Python with a serial version of LAMMPS :link(9_1),h4
From the python directory in the LAMMPS distribution, type
python setup_serial.py build :pre
and then one of these commands:
sudo python setup_serial.py install
python setup_serial.py install --home=~/foo :pre
The "build" command should compile all the needed LAMMPS files,
including its dummy MPI library. The first "install" command will put
the needed files in your Python's site-packages sub-directory, so that
Python can load them. For example, if you installed Python yourself
on a Linux machine, it would typically be somewhere like
/usr/local/lib/python2.5/site-packages. Installing Python packages
this way often requires you to be able to write to the Python
directories, which may require root priveleges, hence the "sudo"
prefix. If this is not the case, you can drop the "sudo".
Alternatively, you can install the LAMMPS files (or any other Python
packages) in your own user space. The second "install" command does
this, where you should replace "foo" with your directory of choice.
If these commands are successful, a {lammps.py} and
{_lammps_serial.so} file will be put in the appropriate directory.
:line
Creating a shared MPI library :link(9_2),h4
A shared library is one that is dynamically loadable, which is what
Python requires. On Linux this is a library file that ends in ".so",
not ".a". Such a shared library is normally not built if you
installed MPI yourself, but it is easy to do. Here is how to do it
for "MPICH"_mpich, a popular open-source version of MPI, distributed
by Argonne National Labs. From within the mpich directory, type
:link(mpich,http://www-unix.mcs.anl.gov/mpi)
./configure --enable-sharedlib=gcc
make
make install :pre
You may need to use "sudo make install" in place of the last line.
The end result should be the file libmpich.so in /usr/local/lib.
IMPORTANT NOTE: If the file libmpich.a already exists in your
installation directory (e.g. /usr/local/lib), you will now have both a
static and shared MPI library. This will be fine for running LAMMPS
from Python since it only uses the shared library. But if you now try
to build LAMMPS by itself as a stand-alone program (cd lammps/src;
make foo) or build other codes that expect to link against libmpich.a,
then those builds will typically fail if the linker uses libmpich.so
instead. This means you will need to remove the file
/usr/local/lib/libmich.so before building LAMMPS again as a
stand-alone code.
:line
Extending Python with a parallel version of LAMMPS :link(9_3),h4
From the python directory, type
python setup.py build :pre
and then one of these commands:
sudo python setup.py install
python setup.py install --home=~/foo :pre
The "build" command should compile all the needed LAMMPS C++ files,
which will require MPI to be installed on your system. This means it
must find both the header file mpi.h and a shared library file,
e.g. libmpich.so if the MPICH version of MPI is installed. See the
preceding section for how to create a shared library version of MPI if
it does not exist. You may need to adjust the "include_dirs" and
"library_dirs" and "libraries" fields in python/setup.py to
insure the Python build finds all the files it needs.
The first "install" command will put the needed files in your Python's
site-packages sub-directory, so that Python can load them. For
example, if you installed Python yourself on a Linux machine, it would
typically be somewhere like /usr/local/lib/python2.5/site-packages.
Installing Python packages this way often requires you to be able to
write to the Python directories, which may require root priveleges,
hence the "sudo" prefix. If this is not the case, you can drop the
"sudo".
Alternatively, you can install the LAMMPS files (or any other Python
packages) in your own user space. The second "install" command does
this, where you should replace "foo" with your directory of choice.
If these commands are successful, a {lammps.py} and {_lammps.so} file
will be put in the appropriate directory.
:line
Extending Python with MPI :link(9_4),h4
There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python.
These include
"pyMPI"_http://pympi.sourceforge.net/
"maroonmpi"_http://code.google.com/p/maroonmpi/
"mpi4py"_http://code.google.com/p/mpi4py/
"myMPI"_http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16
"Pypar"_http://datamining.anu.edu.au/~ole/pypar :ul
All of these except pyMPI work by wrapping the MPI library (which must
be available on your system as a shared library, as discussed above),
and exposing (some portion of) its interface to your Python script.
This means they cannot be used interactively in parallel, since they
do not address the issue of interactive input to multiple instances of
Python running on different processors. The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of python
itself) as a result.
In principle any of these Python/MPI packages should work to invoke
both calls to LAMMPS and MPI itself from a Python script running in
parallel. However, when I downloaded and looked at a few of them,
their docuemtation was incomplete and I had trouble with their
installation. It's not clear if some of the packages are still being
actively developed and supported.
The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous "Numpy
package"_http://numpy.scipy.org be installed in your Python. After
launching python, type
>>> import numpy :pre
to see if it is installed. If not, here is how to install it (version
1.3.0b1 as of April 2009). Unpack the numpy tarball and from its
top-level directory, type
python setup.py build
sudo python setup.py install :pre
The "sudo" is only needed if required to copy Numpy files into your
Python distribution's site-packages directory.
To install Pypar (version pypar-2.1.0_66 as of April 2009), unpack it
and from its "source" directory, type
python setup.py build
sudo python setup.py install :pre
Again, the "sudo" is only needed if required to copy PyPar files into
your Python distribution's site-packages directory.
If you have successully installed Pypar, you should be able to run
python serially and type
>>> import pypar :pre
without error. You should also be able to run python in parallel
on a simple test script
% mpirun -np 4 python test.script :pre
where test.script contains the lines
import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) :pre
and see one line of output for each processor you ran on.
:line
Testing the Python-LAMMPS interface :link(9_5),h4
Before using LAMMPS in a Python program, one more step is needed. The
interface to LAMMPS is via the Python ctypes package, which loads the
shared LAMMPS library via a CDLL() call, which in turn is a wrapper on
the C-library dlopen(). This command is different than a normal
Python "import" and needs to be able to find the LAMMPS shared
library, which is either in the Python site-packages directory or in a
local directory you specified in the "python setup.py install"
command, as described above.
The simplest way to do this is add a line like this to your
.cshrc or other shell start-up file.
setenv LD_LIBRARY_PATH
$\{LD_LIBRARY_PATH\}:/usr/local/lib/python2.5/site-packages :pre
and then execute the shell file to insure the path has been updated.
This will extend the path that dlopen() uses to look for shared
libraries.
To test if the serial LAMMPS library has been successfully installed
(mode 1 above), launch Python and type
>>> from lammps import lammps
>>> lmp = lammps() :pre
If you get no errors, you're ready to use serial LAMMPS from Python.
If you built LAMMPS for parallel use (mode 2 or 3 above), launch
Python in parallel:
% mpirun -np 4 python test.script :pre
where test.script contains the lines
import pypar
from lammps import lammps
lmp = lammps()
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()), lmp
pypar.finalize() :pre
Again, if you get no errors, you're good to go.
Note that if you left out the "import pypar" line from this script,
you would instantiate and run LAMMPS independently on each of the P
processors specified in the mpirun command. You can test if Pypar is
enabling true parallel Python and LAMMPS by adding a line to the above
sequence of commands like lmp.file("in.lj") to run an input script and
see if the LAMMPS run says it ran on P processors or if you get output
from P duplicated 1-processor runs written to the screen. In the
latter case, Pypar is not working correctly.
Note that this line:
from lammps import lammps :pre
will import either the serial or parallel version of the LAMMPS
library, as wrapped by lammps.py. But if you installed both via
setup_serial.py and setup.py, it will always import the parallel
version, since it attempts that first.
Note that if your Python script imports the Pypar package (as above),
so that it can use MPI calls directly, then Pypar initializes MPI for
you. Thus the last line of your Python script should be
pypar.finalize(), to insure MPI is shut down correctly.
Also note that a Python script can be invoked in one of several ways:
% python foo.script
% python -i foo.script
% foo.script
The last command requires that the first line of the script be
something like this:
#!/usr/local/bin/python
#!/usr/local/bin/python -i
where the path points to where you have Python installed, and that you
have made the script file executable:
% chmod +x foo.script
Without the "-i" flag, Python will exit when the script finishes.
With the "-i" flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.
:line
:line
Using LAMMPS from Python :link(9_6),h4
The Python interface to LAMMPS consists of a Python "lammps" module,
the source code for which is in python/lammps.py, which creates a
"lammps" object, with a set of methods that can be invoked on that
object. The sample Python code below assumes you have first imported
the "lammps" module in your Python script and its settings as
follows:
from lammps import lammps
from lammps import LMPINT as INT
from lammps import LMPDOUBLE as DOUBLE
from lammps import LMPIPTR as IPTR
from lammps import LMPDPTR as DPTR
from lammps import LMPDPTRPTR as DPTRPTR :pre
These are the methods defined by the lammps module. If you look
at the file src/library.cpp you will see that they correspond
one-to-one with calls you can make to the LAMMPS library from a C++ or
C or Fortran program.
lmp = lammps() # create a LAMMPS object
lmp = lammps(list) # ditto, with command-line args, list = \["-echo","screen"\] :pre
lmp.close() # destroy a LAMMPS object :pre
lmp.file(file) # run an entire input script, file = "in.lj"
lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" :pre
xlo = lmp.extract_global(name,type) # extract a global quantity
# name = "boxxlo", "nlocal", etc
# type = INT or DOUBLE :pre
coords = lmp.extract_atom(name,type) # extract a per-atom quantity
# name = "x", "type", etc
# type = IPTR or DPTR or DPTRPTR :pre
eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute
v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix
# id = ID of compute or fix
# style = 0 = global data
# 1 = per-atom data
# 2 = local data
# type = 0 = scalar
# 1 = vector
# 2 = array
# i,j = indices of value in global vector or array :pre
var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable
# name = name of variable
# group = group ID (ignored for equal-style variables)
# flag = 0 = equal-style variable
# 1 = atom-style variable :pre
natoms = lmp.get_natoms() # total # of atoms as int
x = lmp.get_coords() # return coords of all atoms in x
lmp.put_coords(x) # set all atom coords via x :pre
:line
The creation of a LAMMPS object does not take an MPI communicator as
an argument. There should be a way to do this, so that the LAMMPS
instance runs on a subset of processors, if desired, but I don't yet
know how from Pypar. So for now, it runs on MPI_COMM_WORLD, which is
all the processors.
The file() and command() methods allow an input script or single
commands to be invoked.
The extract_global(), extract_atom(), extract_compute(),
extract_fix(), and extract_variable() methods return values or
pointers to data structures internal to LAMMPS.
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.
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.
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 "this section"_Section_howto.html#4_15 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
"computes"_compute.html and "fixes"_fix.html for a description of what
they calculate and store.
For extract_variable(), an "equal-style or atom-style
variable"_variable.html is evaluated and its result returned.
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.
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).
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.
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.
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 "atom_modify"_atom_modify.html command for
details. If it is not or if atom IDs are not consecutively ordered,
no coordinates are reset,
The array of coordinates passed to put_coords() must be a ctypes
vector of doubles, allocated and initialized something like this:
from ctypes import *
natoms = lmp.get_atoms()
n3 = 3*natoms
x = (c_double*n3)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.put_coords(x) :pre
Alternatively, you can just change values in the vector returned by
get_coords(), since it is a ctypes vector of doubles.
:line
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:
Add a new interface function to src/library.cpp and
src/library.h. :ulb,l
Verify the new function is syntactically correct by building LAMMPS as
a library - see "this section"_Section_start.html#2_4 of the
manual. :l
Add a wrapper method in the Python LAMMPS module to python/lammps.py
for this interface function. :l
Rebuild the Python wrapper via python/setup_serial.py or
python/setup.py. :l
You should now be able to invoke the new interface function from a
Python script. Isn't ctypes amazing? :l,ule
:line
:line
Example Python scripts that use LAMMPS :link(9_7),h4
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.
trivial.py, read/run a LAMMPS input script via Python,
demo.py, invoke various LAMMPS library interface routines,
simple.py, mimic operation of couple/simple/simple.cpp in Python,
gui.py, GUI go/stop/temperature-slider to control LAMMPS,
plot.py, real-time temeperature plot with GnuPlot via "Pizza.py"_pizza,
viz.py, real-time viz from GL tool in "Pizza.py"_pizza,
vizplotgui.py, combination of viz.py and plot.py and gui.py :tb(c=2)
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.
:link(pizza,http://www.sandia.gov/~sjplimp/pizza.html)

40
doc/Section_start.html
View File

@ -577,36 +577,24 @@ another application can link to.
<P>When used from a C++ program, the library allows one or more LAMMPS
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within your application code, as needed. See the sample code
examples/couple/c++_driver.cpp as an example.
within your application code, as needed.
</P>
<P>When used from a C or Fortran program or a scripting language, the
library has a simple function-style interface, provided in library.cpp
and library.h. See the sample code examples/couple/c_driver.cpp as an
example.
library has a simple function-style interface, provided in
src/library.cpp and src/library.h.
</P>
<P>You can add as many functions as you wish to library.cpp and
library.h. In a general sense, those functions can access LAMMPS data
and return it to the caller or set LAMMPS data values as specified by
the caller. These 4 functions are currently included in library.cpp:
<P>See the sample codes couple/simple/simple.cpp and simple.c as examples
of C++ and C codes that invoke LAMMPS thru its library interface.
There are other examples as well in the couple directory which are
discussed in <A HREF = "Section_howto.html#4_10">this section</A> of the manual.
See <A HREF = "Section_python.html">this section</A> of the manual for a description
of the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface.
</P>
<PRE>void lammps_open(int, char **, MPI_Comm, void **ptr);
void lammps_close(void *ptr);
int lammps_file(void *ptr, char *);
int lammps_command(void *ptr, char *);
</PRE>
<P>The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were <A HREF = "#2_6">command-line arguments</A> when
LAMMPS is run from the command line and a MPI communicator for LAMMPS
to run under. It returns a ptr to the LAMMPS object that is created,
and which should be used in subsequent library calls. Note that
lammps_open() can be called multiple times to create multiple LAMMPS
objects.
</P>
<P>The lammps_close() function is used to shut down LAMMPS and free all
its memory. The lammps_file() and lammps_command() functions are used
to pass a file or string to LAMMPS as if it were an input file or
single command read from an input script.
<P>The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See <A HREF = "Section_howto.html#4_19">this section</A> of the manual
for a description of the interface and how to extend it for your
needs.
</P>
<HR>

40
doc/Section_start.txt
View File

@ -570,36 +570,24 @@ another application can link to.
When used from a C++ program, the library allows one or more LAMMPS
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within your application code, as needed. See the sample code
examples/couple/c++_driver.cpp as an example.
within your application code, as needed.
When used from a C or Fortran program or a scripting language, the
library has a simple function-style interface, provided in library.cpp
and library.h. See the sample code examples/couple/c_driver.cpp as an
example.
library has a simple function-style interface, provided in
src/library.cpp and src/library.h.
You can add as many functions as you wish to library.cpp and
library.h. In a general sense, those functions can access LAMMPS data
and return it to the caller or set LAMMPS data values as specified by
the caller. These 4 functions are currently included in library.cpp:
See the sample codes couple/simple/simple.cpp and simple.c as examples
of C++ and C codes that invoke LAMMPS thru its library interface.
There are other examples as well in the couple directory which are
discussed in "this section"_Section_howto.html#4_10 of the manual.
See "this section"_Section_python.html of the manual for a description
of the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface.
void lammps_open(int, char **, MPI_Comm, void **ptr);
void lammps_close(void *ptr);
int lammps_file(void *ptr, char *);
int lammps_command(void *ptr, char *); :pre
The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were "command-line arguments"_#2_6 when
LAMMPS is run from the command line and a MPI communicator for LAMMPS
to run under. It returns a ptr to the LAMMPS object that is created,
and which should be used in subsequent library calls. Note that
lammps_open() can be called multiple times to create multiple LAMMPS
objects.
The lammps_close() function is used to shut down LAMMPS and free all
its memory. The lammps_file() and lammps_command() functions are used
to pass a file or string to LAMMPS as if it were an input file or
single command read from an input script.
The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See "this section"_Section_howto.html#4_19 of the manual
for a description of the interface and how to extend it for your
needs.
:line

2
doc/read_restart.html
View File

@ -43,7 +43,7 @@ these cases. Certain fixes will also not restart exactly, though they
should provide statistically similar results. These include <A HREF = "fix_shake.html">fix
shake</A> and <A HREF = "fix_langevin.html">fix langevin</A>. If a
restarted run is immediately different than the run which produced the
restart file, it could be a LAMMPS bug, so consider <A HREF = "Section_errors.html#9_2">reporting
restart file, it could be a LAMMPS bug, so consider <A HREF = "Section_errors.html#10_2">reporting
it</A> if you think the behavior is wrong.
</P>
<P>Because restart files are binary, they may not be portable to other

2
doc/read_restart.txt
View File

@ -41,7 +41,7 @@ should provide statistically similar results. These include "fix
shake"_fix_shake.html and "fix langevin"_fix_langevin.html. If a
restarted run is immediately different than the run which produced the
restart file, it could be a LAMMPS bug, so consider "reporting
it"_Section_errors.html#9_2 if you think the behavior is wrong.
it"_Section_errors.html#10_2 if you think the behavior is wrong.
Because restart files are binary, they may not be portable to other
machines. They can be converted to ASCII data files using the