ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files

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>