lijiext
/
lammps
mirror of https://github.com/lammps/lammps.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

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

This commit is contained in:
sjplimp 2012-08-11 19:27:54 +00:00
parent 45ccb34ac3
commit f699bd6ca8
4 changed files with 466 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

286
doc/Section_python.html
View File

@ -16,7 +16,7 @@ interface.
</P> </P>
<UL><LI>11.1 <A HREF = "#py_1">Setting necessary environment variables</A> <UL><LI>11.1 <A HREF = "#py_1">Setting necessary environment variables</A>
<LI>11.2 <A HREF = "#py_2">Building LAMMPS as a shared library</A> <LI>11.2 <A HREF = "#py_2">Building LAMMPS as a shared library</A>
<LI>11.3 <A HREF = "#py_3">Extending Python with MPI</A> <LI>11.3 <A HREF = "#py_3">Extending Python with MPI to run in parallel</A>
<LI>11.4 <A HREF = "#py_4">Testing the Python-LAMMPS interface</A> <LI>11.4 <A HREF = "#py_4">Testing the Python-LAMMPS interface</A>
<LI>11.5 <A HREF = "#py_5">Using LAMMPS from Python</A> <LI>11.5 <A HREF = "#py_5">Using LAMMPS from Python</A>
<LI>11.6 <A HREF = "#py_6">Example Python scripts that use LAMMPS</A> <LI>11.6 <A HREF = "#py_6">Example Python scripts that use LAMMPS</A>
@ -34,12 +34,12 @@ read what you type.
<P><A HREF = "http://www.python.org">Python</A> is a powerful scripting and programming <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 language which can be used to wrap software like LAMMPS and other
packages. It can be used to glue multiple pieces of software 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#howto_10">this together, e.g. to run a coupled or multiscale model. See <A HREF = "Section_howto.html#howto_10">Section
section</A> of the manual and the couple section</A> of the manual and the couple
directory of the distribution for more ideas about coupling LAMMPS to directory of the distribution for more ideas about coupling LAMMPS to
other codes. See <A HREF = "Section_start.html#start_5">Section_start 4</A> about other codes. See <A HREF = "Section_start.html#start_5">Section_start 4</A> about
how to build LAMMPS as a library, and <A HREF = "Section_howto.html#howto_19">this how to build LAMMPS as a library, and <A HREF = "Section_howto.html#howto_19">Section_howto
section</A> for a description of the library 19</A> for a description of the library
interface provided in src/library.cpp and src/library.h and how to 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 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. is exposed to Python. It is designed to be easy to add functions to.
@ -61,7 +61,9 @@ LAMMPS thru Python will be negligible.
<P>Before using LAMMPS from a Python script, you have to do two things. <P>Before using LAMMPS from a Python script, you have to do two things.
You need to set two environment variables. And you need to build You need to set two environment variables. And you need to build
LAMMPS as a dynamic shared library, so it can be loaded by Python. LAMMPS as a dynamic shared library, so it can be loaded by Python.
Both these steps are discussed below. Both these steps are discussed below. If you wish to run LAMMPS in
parallel from Python, you also need to extend your Python with MPI.
This is also discussed below.
</P> </P>
<P>The Python wrapper for LAMMPS uses the amazing and magical (to me) <P>The Python wrapper for LAMMPS uses the amazing and magical (to me)
"ctypes" package in Python, which auto-generates the interface code "ctypes" package in Python, which auto-generates the interface code
@ -99,18 +101,11 @@ the following section.
</P> </P>
<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src <PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src
</PRE> </PRE>
<P>Note that a LAMMPS build may depend on several auxiliary libraries, <P>As discussed below, if your LAMMPS build includes auxiliary libraries,
which are specied in your low-level src/Makefile.foo file. For they must also be available as shared libraries for Python to
example, an MPI library, the FFTW library, a JPEG library, etc. successfully load LAMMPS. If they are not in default places where the
Depending on what LAMMPS packages you have installed, you may operating system can find them, then you also have to add their paths
pre-build additional libraries in the lib directories, which are linked to the LD_LIBRARY_PATH environment variable.
to in your LAMMPS build.
</P>
<P>As discussed below, in you are including those options in LAMMPS, all
of the auxiliary libraries have to be available as shared libraries
for Python to successfully load LAMMPS. If they are not in default
places where the operating system can find them, then you also have to
add their paths to the LD_LIBRARY_PATH environment variable.
</P> </P>
<P>For example, if you are using the dummy MPI library provided in <P>For example, if you are using the dummy MPI library provided in
src/STUBS, you need to add something like this to your ~/.cshrc file: src/STUBS, you need to add something like this to your ~/.cshrc file:
@ -126,12 +121,46 @@ something like this to your ~/.cshrc file:
<A NAME = "py_2"></A><H4>11.2 Building LAMMPS as a shared library <A NAME = "py_2"></A><H4>11.2 Building LAMMPS as a shared library
</H4> </H4>
<P>A shared library is one that is dynamically loadable, which is what <P>Instructions on how to build LAMMPS as a shared library are given in
Python requires. On Linux this is a library file that ends in ".so", <A HREF = "Section_start.html#start_5">Section_start 5</A>. A shared library is one
not ".a". Such a shared library is normally not built if you that is dynamically loadable, which is what Python requires. On Linux
installed MPI yourself, but it is easy to do. Here is how to do it this is a library file that ends in ".so", not ".a".
for <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH</A>, a popular open-source version of MPI, distributed </P>
by Argonne National Labs. From within the mpich directory, type <P>>From the src directory, type
</P>
<P>make makeshlib
make -f Makefile.shlib foo
</P>
<P>where foo is the machine target name, such as linux or g++ or serial.
This should create the file liblmp_foo.so in the src directory, as
well as a soft link liblmp.so which is what the Python wrapper will
load by default. If you are building multiple machine versions of the
shared library, the soft link is always set to the most recently built
version.
</P>
<P>Note that as discussed in below, a LAMMPS build may depend on several
auxiliary libraries, which are specified in your low-level
src/Makefile.foo file. For example, an MPI library, the FFTW library,
a JPEG library, etc. Depending on what LAMMPS packages you have
installed, the build may also require additional libraries from the
lib directories, such as lib/atc/libatc.so or lib/reax/libreax.so.
</P>
<P>You must insure that each of these libraries exist in shared library
form (*.so file for Linux systems), or either the LAMMPS shared
library build or the Python load of the library will fail. For the
load to be successful all the shared libraries must also be in
directories that the operating system checks. See the discussion in
the preceding section about the LD_LIBRARY_PATH environment variable
for how to insure this.
</P>
<P>Note that some system libraries, such as MPI, if you installed it
yourself, may not be built by default as shared libraries. The build
instructions for the library should tell you how to do this.
</P>
<P>For example, here is how to build and install the <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH
library</A>, a popular open-source version of MPI, distributed by
Argonne National Labs, as a shared library in the default
/usr/local/lib location:
</P> </P>
@ -139,53 +168,23 @@ by Argonne National Labs. From within the mpich directory, type
make make
make install make install
</PRE> </PRE>
<P>You may need to use "sudo make install" in place of the last line. <P>You may need to use "sudo make install" in place of the last line if
The end result should be the file libmpich.so in /usr/local/lib. you do not have write priveleges for /usr/local/lib. The end result
should be the file /usr/local/lib/libmpich.so.
</P> </P>
<P>Before proceeding, there are 2 items to note. <P>Note that not all of the auxiliary libraries provided with LAMMPS have
shared-library Makefiles in their lib directories. Typically this
simply requires a Makefile.foo that adds a -fPIC switch when files are
compiled and a "-fPIC -shared" switches when the library is linked
with a C++ (or Fortran) compiler, as well as an output target that
ends in ".so", like libatc.o. As we or others create and contribute
these Makefiles, we will add them to the LAMMPS distribution.
</P> </P>
<P>(2) Any library wrapped by Python, including LAMMPS, must be built as <A NAME = "py_3"></A><H4>11.3 Extending Python with MPI to run in parallel
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#start_3">this
section</A> of the manual for a discussion of
LAMMPS packages. 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>
<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 may fail if the linker uses libmpich.so instead. If
this happens, it means you will need to remove the file
/usr/local/lib/libmich.so before building LAMMPS again as a
stand-alone code.
</P>
<A NAME = "py_3"></A><H4>11.3 Extending Python with MPI
</H4> </H4>
<P>If <P>If you wish to run LAMMPS in parallel from Python, you need to extend
your Python script will run in parallel and you want to be able to your Python with an interface to MPI. This also allows you to
invoke MPI calls directly from Python, you will also need to extend make MPI calls directly from Python in your script, if you desire.
your Python with an interface to MPI.
</P> </P>
<P>There are several Python packages available that purport to wrap MPI <P>There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python. as a library and allow MPI functions to be called from Python.
@ -201,26 +200,26 @@ as a library and allow MPI functions to be called from Python.
<P>All of these except pyMPI work by wrapping the MPI library (which must <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), be available on your system as a shared library, as discussed above),
and exposing (some portion of) its interface to your Python script. and exposing (some portion of) its interface to your Python script.
This means they cannot be used interactively in parallel, since they This means Python cannot be used interactively in parallel, since they
do not address the issue of interactive input to multiple instances of do not address the issue of interactive input to multiple instances of
Python running on different processors. The one exception is pyMPI, Python running on different processors. The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of python believe) creates a new alternate executable (in place of "python"
itself) as a result. itself) as a result.
</P> </P>
<P>In principle any of these Python/MPI packages should work to invoke <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 LAMMPS in parallel and MPI calls themselves from a Python script which
parallel. However, when I downloaded and looked at a few of them, is itself running in parallel. However, when I downloaded and looked
their docuemtation was incomplete and I had trouble with their at a few of them, their documentation was incomplete and I had trouble
installation. It's not clear if some of the packages are still being with their installation. It's not clear if some of the packages are
actively developed and supported. still being actively developed and supported.
</P> </P>
<P>The one I recommend, since I have successfully used it with LAMMPS, is <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 Pypar. Pypar requires the ubiquitous <A HREF = "http://numpy.scipy.org">Numpy
package</A> be installed in your Python. After package</A> be installed in your Python. After
launching python, type launching python, type
</P> </P>
<PRE>>>> import numpy <PRE>import numpy
</PRE> </PRE>
<P>to see if it is installed. If not, here is how to install it (version <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 1.3.0b1 as of April 2009). Unpack the numpy tarball and from its
@ -244,58 +243,108 @@ your Python distribution's site-packages directory.
<P>If you have successully installed Pypar, you should be able to run <P>If you have successully installed Pypar, you should be able to run
python serially and type python serially and type
</P> </P>
<PRE>>>> import pypar <PRE>import pypar
</PRE> </PRE>
<P>without error. You should also be able to run python in parallel <P>without error. You should also be able to run python in parallel
on a simple test script on a simple test script
</P> </P>
<PRE>% mpirun -np 4 python test.script <PRE>% mpirun -np 4 python test.py
</PRE> </PRE>
<P>where test.script contains the lines <P>where test.py contains the lines
</P> </P>
<PRE>import pypar <PRE>import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())
</PRE> </PRE>
<P>and see one line of output for each processor you ran on. <P>and see one line of output for each processor you run on.
</P> </P>
<HR> <HR>
<A NAME = "py_4"></A><H4>11.4 Testing the Python-LAMMPS interface <A NAME = "py_4"></A><H4>11.4 Testing the Python-LAMMPS interface
</H4> </H4>
<P>To test if LAMMPS is now callable from Python, launch Python and type: <P>To test if LAMMPS is callable from Python, launch Python interactively
and type:
</P> </P>
<PRE>>>> from lammps import lammps <PRE>>>> from lammps import lammps
>>> lmp = lammps() >>> lmp = lammps()
</PRE> </PRE>
<P>If you get no errors, you're ready to use LAMMPS from Python. <P>If you get no errors, you're ready to use LAMMPS from Python.
If the load fails, the most common error to see is
</P> </P>
<PRE>% mpirun -np 4 python test.script <P>"CDLL: asdfasdfasdf"
</P>
<P>which means Python was unable to load the LAMMPS shared library. This
can occur if it can't find the LAMMMPS library; see the environment
variable discussion <A HREF = "#python_1">above</A>. Or if it can't find one of the
auxiliary libraries that was specified in the LAMMPS build, in a
shared dynamic library format. This includes all libraries needed by
main LAMMPS (e.g. MPI or FFTW or JPEG), system libraries needed by
main LAMMPS (e.g. extra libs needed by MPI), or packages you have
installed that require libraries provided with LAMMPS (e.g. the
USER-ATC package require lib/atc/libatc.so) or system libraries
(e.g. BLAS or Fortran-to-C libraries) listed in the
lib/package/Makefile.lammps file. Again, all of these must be
available as shared libraries, or the Python load will fail.
</P>
<P>Python (actually the operating system) isn't verbose about telling you
why the load failed, so go through the steps above and in
<A HREF = "Section_start.html#start_5">Section_start 5</A> carefully.
</P>
<H5><B>Test LAMMPS and Python in serial:</B>
</H5>
<P>To run a LAMMPS test in serial, type these lines into Python
interactively from the bench directory:
</P>
<PRE>>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
</PRE> </PRE>
<P>where test.script contains the lines <P>Or put the same lines in the file test.py and run it as
</P>
<PRE>% python test.py
</PRE>
<P>Either way, you should see the results of running the in.lj benchmark
on a single processor appear on the screen, the same as if you had
typed something like:
</P>
<PRE>lmp_g++ < in.lj
</PRE>
<H5><B>Test LAMMPS and Python in parallel:</B>
</H5>
<P>To run LAMMPS in parallel, assuming you have installed the
<A HREF = "http://datamining.anu.edu.au/~ole/pypar">Pypar</A> package as discussed
above, create a test.py file containing these lines:
</P> </P>
<PRE>import pypar <PRE>import pypar
from lammps import lammps from lammps import lammps
lmp = lammps() lmp = lammps()
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()), lmp lmp.file("in.lj")
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
pypar.finalize() pypar.finalize()
</PRE> </PRE>
<P>Again, if you get no errors, you're good to go. <P>You can then run it in parallel as:
</P> </P>
<P>Note that if you left out the "import pypar" line from this script, <PRE>% mpirun -np 4 python test.py
you would instantiate and run LAMMPS independently on each of the P </PRE>
processors specified in the mpirun command. You can test if Pypar is <P>and you should see the same output as if you had typed
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>
<P>Note that if your Python script imports the Pypar package (as above), <PRE>% mpirun -np 4 lmp_g++ < in.lj
so that it can use MPI calls directly, then Pypar initializes MPI for </PRE>
you. Thus the last line of your Python script should be <P>Note that if you leave out the 3 lines from test.py that specify Pypar
pypar.finalize(), to insure MPI is shut down correctly. commands you will instantiate and run LAMMPS independently on each of
the P processors specified in the mpirun command. In this case you
should get 4 sets of output, each showing that a run was made on a
single processor, instead of one set of output showing that it ran on
4 processors. If the 1-processor outputs occur, it means that Pypar
is not working correctly.
</P> </P>
<P>Also note that a Python script can be invoked in one of several ways: <P>Also note that once you import the PyPar module, Pypar initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the Pypar documentation. The last line of your Python
script should be pypar.finalize(), to insure MPI is shut down
correctly.
</P>
<P>Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
</P> </P>
<P>% python foo.script <P>% python foo.script
% python -i foo.script % python -i foo.script
@ -328,8 +377,9 @@ Python on a single processor, not in parallel.
the source code for which is in python/lammps.py, which creates a 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 "lammps" object, with a set of methods that can be invoked on that
object. The sample Python code below assumes you have first imported object. The sample Python code below assumes you have first imported
the "lammps" module in your Python script and its settings as the "lammps" module in your Python script. You can also include its
follows: settings as follows, which are useful in test return values from some
of the methods described below:
</P> </P>
<PRE>from lammps import lammps <PRE>from lammps import lammps
from lammps import LMPINT as INT from lammps import LMPINT as INT
@ -343,8 +393,10 @@ 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 one-to-one with calls you can make to the LAMMPS library from a C++ or
C or Fortran program. C or Fortran program.
</P> </P>
<PRE>lmp = lammps() # create a LAMMPS object <PRE>lmp = lammps() # create a LAMMPS object using the default liblmp.so library
lmp = lammps(list) # ditto, with command-line args, list = ["-echo","screen"] lmp = lammps("g++") # create a LAMMPS object using the liblmp_g++.so library
lmp = lammps("",list) # ditto, with command-line args, list = ["-echo","screen"]
lmp = lammps("g++",list)
</PRE> </PRE>
<PRE>lmp.close() # destroy a LAMMPS object <PRE>lmp.close() # destroy a LAMMPS object
</PRE> </PRE>
@ -382,12 +434,23 @@ lmp.put_coords(x) # set all atom coords via x
</PRE> </PRE>
<HR> <HR>
<P>The creation of a LAMMPS object does not take an MPI communicator as <P>IMPORTANT NOTE: Currenlty, the creation of a LAMMPS object does not
an argument. There should be a way to do this, so that the LAMMPS take an MPI communicator as an argument. There should be a way to do
instance runs on a subset of processors, if desired, but I don't yet this, so that the LAMMPS instance runs on a subset of processors if
know how from Pypar. So for now, it runs on MPI_COMM_WORLD, which is desired, but I don't know how to do it from Pypar. So for now, it
all the processors. runs on MPI_COMM_WORLD, which is all the processors. If someone
figures out how to do this with one or more of the Python wrappers for
MPI, like Pypar, please let us know and we will amend these doc pages.
</P> </P>
<P>Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
</P>
<PRE>from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")
</PRE>
<P>The file() and command() methods allow an input script or single <P>The file() and command() methods allow an input script or single
commands to be invoked. commands to be invoked.
</P> </P>
@ -497,15 +560,10 @@ following steps:
<UL><LI>Add a new interface function to src/library.cpp and <UL><LI>Add a new interface function to src/library.cpp and
src/library.h. src/library.h.
<LI>Verify the new function is syntactically correct by building LAMMPS as <LI>Rebuild LAMMPS as a shared library.
a library - see <A HREF = "Section_start.html#start_5">Section_start 4</A> of the
manual.
<LI>Add a wrapper method in the Python LAMMPS module to python/lammps.py <LI>Add a wrapper method to python/lammps.py for this interface
for this interface function. 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 <LI>You should now be able to invoke the new interface function from a
Python script. Isn't ctypes amazing? Python script. Isn't ctypes amazing?

287
doc/Section_python.txt
View File

@ -13,7 +13,7 @@ interface.
11.1 "Setting necessary environment variables"_#py_1 11.1 "Setting necessary environment variables"_#py_1
11.2 "Building LAMMPS as a shared library"_#py_2 11.2 "Building LAMMPS as a shared library"_#py_2
11.3 "Extending Python with MPI"_#py_3 11.3 "Extending Python with MPI to run in parallel"_#py_3
11.4 "Testing the Python-LAMMPS interface"_#py_4 11.4 "Testing the Python-LAMMPS interface"_#py_4
11.5 "Using LAMMPS from Python"_#py_5 11.5 "Using LAMMPS from Python"_#py_5
11.6 "Example Python scripts that use LAMMPS"_#py_6 :ul 11.6 "Example Python scripts that use LAMMPS"_#py_6 :ul
@ -31,12 +31,12 @@ read what you type.
"Python"_http://www.python.org is a powerful scripting and programming "Python"_http://www.python.org is a powerful scripting and programming
language which can be used to wrap software like LAMMPS and other language which can be used to wrap software like LAMMPS and other
packages. It can be used to glue multiple pieces of software packages. It can be used to glue multiple pieces of software
together, e.g. to run a coupled or multiscale model. See "this together, e.g. to run a coupled or multiscale model. See "Section
section"_Section_howto.html#howto_10 of the manual and the couple section"_Section_howto.html#howto_10 of the manual and the couple
directory of the distribution for more ideas about coupling LAMMPS to directory of the distribution for more ideas about coupling LAMMPS to
other codes. See "Section_start 4"_Section_start.html#start_5 about other codes. See "Section_start 4"_Section_start.html#start_5 about
how to build LAMMPS as a library, and "this how to build LAMMPS as a library, and "Section_howto
section"_Section_howto.html#howto_19 for a description of the library 19"_Section_howto.html#howto_19 for a description of the library
interface provided in src/library.cpp and src/library.h and how to 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 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. is exposed to Python. It is designed to be easy to add functions to.
@ -58,7 +58,9 @@ LAMMPS thru Python will be negligible.
Before using LAMMPS from a Python script, you have to do two things. Before using LAMMPS from a Python script, you have to do two things.
You need to set two environment variables. And you need to build You need to set two environment variables. And you need to build
LAMMPS as a dynamic shared library, so it can be loaded by Python. LAMMPS as a dynamic shared library, so it can be loaded by Python.
Both these steps are discussed below. Both these steps are discussed below. If you wish to run LAMMPS in
parallel from Python, you also need to extend your Python with MPI.
This is also discussed below.
The Python wrapper for LAMMPS uses the amazing and magical (to me) The Python wrapper for LAMMPS uses the amazing and magical (to me)
"ctypes" package in Python, which auto-generates the interface code "ctypes" package in Python, which auto-generates the interface code
@ -95,18 +97,11 @@ For the csh or tcsh shells, you could add something like this to your
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
Note that a LAMMPS build may depend on several auxiliary libraries, As discussed below, if your LAMMPS build includes auxiliary libraries,
which are specied in your low-level src/Makefile.foo file. For they must also be available as shared libraries for Python to
example, an MPI library, the FFTW library, a JPEG library, etc. successfully load LAMMPS. If they are not in default places where the
Depending on what LAMMPS packages you have installed, you may operating system can find them, then you also have to add their paths
pre-build additional libraries in the lib directories, which are linked to the LD_LIBRARY_PATH environment variable.
to in your LAMMPS build.
As discussed below, in you are including those options in LAMMPS, all
of the auxiliary libraries have to be available as shared libraries
for Python to successfully load LAMMPS. If they are not in default
places where the operating system can find them, then you also have to
add their paths to the LD_LIBRARY_PATH environment variable.
For example, if you are using the dummy MPI library provided in For example, if you are using the dummy MPI library provided in
src/STUBS, you need to add something like this to your ~/.cshrc file: src/STUBS, you need to add something like this to your ~/.cshrc file:
@ -122,18 +117,46 @@ setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/atc :pre
11.2 Building LAMMPS as a shared library :link(py_2),h4 11.2 Building LAMMPS as a shared library :link(py_2),h4
Instructions on how to build LAMMPS as a shared library are given in
"Section_start 5"_Section_start.html#start_5. 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".
>From the src directory, type
make makeshlib
make -f Makefile.shlib foo
where foo is the machine target name, such as linux or g++ or serial.
This should create the file liblmp_foo.so in the src directory, as
well as a soft link liblmp.so which is what the Python wrapper will
load by default. If you are building multiple machine versions of the
shared library, the soft link is always set to the most recently built
version.
Note that as discussed in below, a LAMMPS build may depend on several
auxiliary libraries, which are specified in your low-level
src/Makefile.foo file. For example, an MPI library, the FFTW library,
a JPEG library, etc. Depending on what LAMMPS packages you have
installed, the build may also require additional libraries from the
lib directories, such as lib/atc/libatc.so or lib/reax/libreax.so.
You must insure that each of these libraries exist in shared library
form (*.so file for Linux systems), or either the LAMMPS shared
library build or the Python load of the library will fail. For the
load to be successful all the shared libraries must also be in
directories that the operating system checks. See the discussion in
the preceding section about the LD_LIBRARY_PATH environment variable
for how to insure this.
A shared library is one that is dynamically loadable, which is what Note that some system libraries, such as MPI, if you installed it
Python requires. On Linux this is a library file that ends in ".so", yourself, may not be built by default as shared libraries. The build
not ".a". Such a shared library is normally not built if you instructions for the library should tell you how to do this.
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 For example, here is how to build and install the "MPICH
by Argonne National Labs. From within the mpich directory, type library"_mpich, a popular open-source version of MPI, distributed by
Argonne National Labs, as a shared library in the default
/usr/local/lib location:
:link(mpich,http://www-unix.mcs.anl.gov/mpi) :link(mpich,http://www-unix.mcs.anl.gov/mpi)
@ -141,62 +164,23 @@ by Argonne National Labs. From within the mpich directory, type
make make
make install :pre make install :pre
You may need to use "sudo make install" in place of the last line. You may need to use "sudo make install" in place of the last line if
The end result should be the file libmpich.so in /usr/local/lib. you do not have write priveleges for /usr/local/lib. The end result
should be the file /usr/local/lib/libmpich.so.
Note that not all of the auxiliary libraries provided with LAMMPS have
shared-library Makefiles in their lib directories. Typically this
simply requires a Makefile.foo that adds a -fPIC switch when files are
compiled and a "-fPIC -shared" switches when the library is linked
with a C++ (or Fortran) compiler, as well as an output target that
ends in ".so", like libatc.o. As we or others create and contribute
these Makefiles, we will add them to the LAMMPS distribution.
11.3 Extending Python with MPI to run in parallel :link(py_3),h4
If you wish to run LAMMPS in parallel from Python, you need to extend
your Python with an interface to MPI. This also allows you to
Before proceeding, there are 2 items to note. make MPI calls directly from Python in your script, if you desire.
(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#start_3 of the manual for a discussion of
LAMMPS packages. 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.
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 may fail if the linker uses libmpich.so instead. If
this happens, it means you will need to remove the file
/usr/local/lib/libmich.so before building LAMMPS again as a
stand-alone code.
11.3 Extending Python with MPI :link(py_3),h4
If
your Python script will run in parallel and you want to be able to
invoke MPI calls directly from Python, you will also need to extend
your Python with an interface to MPI.
There are several Python packages available that purport to wrap MPI There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python. as a library and allow MPI functions to be called from Python.
@ -212,26 +196,26 @@ These include
All of these except pyMPI work by wrapping the MPI library (which must 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), be available on your system as a shared library, as discussed above),
and exposing (some portion of) its interface to your Python script. and exposing (some portion of) its interface to your Python script.
This means they cannot be used interactively in parallel, since they This means Python cannot be used interactively in parallel, since they
do not address the issue of interactive input to multiple instances of do not address the issue of interactive input to multiple instances of
Python running on different processors. The one exception is pyMPI, Python running on different processors. The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of python believe) creates a new alternate executable (in place of "python"
itself) as a result. itself) as a result.
In principle any of these Python/MPI packages should work to invoke 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 LAMMPS in parallel and MPI calls themselves from a Python script which
parallel. However, when I downloaded and looked at a few of them, is itself running in parallel. However, when I downloaded and looked
their docuemtation was incomplete and I had trouble with their at a few of them, their documentation was incomplete and I had trouble
installation. It's not clear if some of the packages are still being with their installation. It's not clear if some of the packages are
actively developed and supported. still being actively developed and supported.
The one I recommend, since I have successfully used it with LAMMPS, is The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous "Numpy Pypar. Pypar requires the ubiquitous "Numpy
package"_http://numpy.scipy.org be installed in your Python. After package"_http://numpy.scipy.org be installed in your Python. After
launching python, type launching python, type
>>> import numpy :pre import numpy :pre
to see if it is installed. If not, here is how to install it (version 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 1.3.0b1 as of April 2009). Unpack the numpy tarball and from its
@ -255,60 +239,108 @@ your Python distribution's site-packages directory.
If you have successully installed Pypar, you should be able to run If you have successully installed Pypar, you should be able to run
python serially and type python serially and type
>>> import pypar :pre import pypar :pre
without error. You should also be able to run python in parallel without error. You should also be able to run python in parallel
on a simple test script on a simple test script
% mpirun -np 4 python test.script :pre % mpirun -np 4 python test.py :pre
where test.script contains the lines where test.py contains the lines
import pypar import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) :pre print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) :pre
and see one line of output for each processor you ran on. and see one line of output for each processor you run on.
:line :line
11.4 Testing the Python-LAMMPS interface :link(py_4),h4 11.4 Testing the Python-LAMMPS interface :link(py_4),h4
To test if LAMMPS is now callable from Python, launch Python and type: To test if LAMMPS is callable from Python, launch Python interactively
and type:
>>> from lammps import lammps >>> from lammps import lammps
>>> lmp = lammps() :pre >>> lmp = lammps() :pre
If you get no errors, you're ready to use LAMMPS from Python. If you get no errors, you're ready to use LAMMPS from Python.
If the load fails, the most common error to see is
"CDLL: asdfasdfasdf"
which means Python was unable to load the LAMMPS shared library. This
can occur if it can't find the LAMMMPS library; see the environment
variable discussion "above"_#python_1. Or if it can't find one of the
auxiliary libraries that was specified in the LAMMPS build, in a
shared dynamic library format. This includes all libraries needed by
main LAMMPS (e.g. MPI or FFTW or JPEG), system libraries needed by
main LAMMPS (e.g. extra libs needed by MPI), or packages you have
installed that require libraries provided with LAMMPS (e.g. the
USER-ATC package require lib/atc/libatc.so) or system libraries
(e.g. BLAS or Fortran-to-C libraries) listed in the
lib/package/Makefile.lammps file. Again, all of these must be
available as shared libraries, or the Python load will fail.
% mpirun -np 4 python test.script :pre Python (actually the operating system) isn't verbose about telling you
why the load failed, so go through the steps above and in
"Section_start 5"_Section_start.html#start_5 carefully.
where test.script contains the lines [Test LAMMPS and Python in serial:] :h5
To run a LAMMPS test in serial, type these lines into Python
interactively from the bench directory:
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj") :pre
Or put the same lines in the file test.py and run it as
% python test.py :pre
Either way, you should see the results of running the in.lj benchmark
on a single processor appear on the screen, the same as if you had
typed something like:
lmp_g++ < in.lj :pre
[Test LAMMPS and Python in parallel:] :h5
To run LAMMPS in parallel, assuming you have installed the
"Pypar"_http://datamining.anu.edu.au/~ole/pypar package as discussed
above, create a test.py file containing these lines:
import pypar import pypar
from lammps import lammps from lammps import lammps
lmp = lammps() lmp = lammps()
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()), lmp lmp.file("in.lj")
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
pypar.finalize() :pre pypar.finalize() :pre
Again, if you get no errors, you're good to go. You can then run it in parallel as:
Note that if you left out the "import pypar" line from this script, % mpirun -np 4 python test.py :pre
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 if your Python script imports the Pypar package (as above), and you should see the same output as if you had typed
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: % mpirun -np 4 lmp_g++ < in.lj :pre
Note that if you leave out the 3 lines from test.py that specify Pypar
commands you will instantiate and run LAMMPS independently on each of
the P processors specified in the mpirun command. In this case you
should get 4 sets of output, each showing that a run was made on a
single processor, instead of one set of output showing that it ran on
4 processors. If the 1-processor outputs occur, it means that Pypar
is not working correctly.
Also note that once you import the PyPar module, Pypar initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the Pypar documentation. The last line of your Python
script should be pypar.finalize(), to insure MPI is shut down
correctly.
Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
% python foo.script % python foo.script
% python -i foo.script % python -i foo.script
@ -340,8 +372,9 @@ The Python interface to LAMMPS consists of a Python "lammps" module,
the source code for which is in python/lammps.py, which creates a 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 "lammps" object, with a set of methods that can be invoked on that
object. The sample Python code below assumes you have first imported object. The sample Python code below assumes you have first imported
the "lammps" module in your Python script and its settings as the "lammps" module in your Python script. You can also include its
follows: settings as follows, which are useful in test return values from some
of the methods described below:
from lammps import lammps from lammps import lammps
from lammps import LMPINT as INT from lammps import LMPINT as INT
@ -355,8 +388,10 @@ 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 one-to-one with calls you can make to the LAMMPS library from a C++ or
C or Fortran program. C or Fortran program.
lmp = lammps() # create a LAMMPS object lmp = lammps() # create a LAMMPS object using the default liblmp.so library
lmp = lammps(list) # ditto, with command-line args, list = \["-echo","screen"\] :pre lmp = lammps("g++") # create a LAMMPS object using the liblmp_g++.so library
lmp = lammps("",list) # ditto, with command-line args, list = \["-echo","screen"\]
lmp = lammps("g++",list) :pre
lmp.close() # destroy a LAMMPS object :pre lmp.close() # destroy a LAMMPS object :pre
@ -394,11 +429,22 @@ lmp.put_coords(x) # set all atom coords via x :pre
:line :line
The creation of a LAMMPS object does not take an MPI communicator as IMPORTANT NOTE: Currenlty, the creation of a LAMMPS object does not
an argument. There should be a way to do this, so that the LAMMPS take an MPI communicator as an argument. There should be a way to do
instance runs on a subset of processors, if desired, but I don't yet this, so that the LAMMPS instance runs on a subset of processors if
know how from Pypar. So for now, it runs on MPI_COMM_WORLD, which is desired, but I don't know how to do it from Pypar. So for now, it
all the processors. runs on MPI_COMM_WORLD, which is all the processors. If someone
figures out how to do this with one or more of the Python wrappers for
MPI, like Pypar, please let us know and we will amend these doc pages.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2") :pre
The file() and command() methods allow an input script or single The file() and command() methods allow an input script or single
commands to be invoked. commands to be invoked.
@ -509,15 +555,10 @@ following steps:
Add a new interface function to src/library.cpp and Add a new interface function to src/library.cpp and
src/library.h. :ulb,l src/library.h. :ulb,l
Verify the new function is syntactically correct by building LAMMPS as Rebuild LAMMPS as a shared library. :l
a library - see "Section_start 4"_Section_start.html#start_5 of the
manual. :l
Add a wrapper method in the Python LAMMPS module to python/lammps.py Add a wrapper method to python/lammps.py for this interface
for this interface function. :l 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 You should now be able to invoke the new interface function from a
Python script. Isn't ctypes amazing? :l,ule Python script. Isn't ctypes amazing? :l,ule

84
doc/Section_start.html
View File

@ -773,37 +773,77 @@ input scripts.
<H4><A NAME = "start_5"></A>2.5 Building LAMMPS as a library <H4><A NAME = "start_5"></A>2.5 Building LAMMPS as a library
</H4> </H4>
<P>LAMMPS itself can be built as a library, which can then be called from <P>LAMMPS can be built as either a static or shared library, which can
another application or a scripting language. See <A HREF = "Section_howto.html#howto_10">this then be called from another application or a scripting language. See
section</A> for more info on coupling LAMMPS <A HREF = "Section_howto.html#howto_10">this section</A> for more info on coupling
to other codes. Building LAMMPS as a library is done by typing LAMMPS to other codes. See <A HREF = "Section_python.html">this section</A> for
more info on wrapping and running LAMMPS from Python.
</P>
<P>To build LAMMPS as a static library (*.a file on Linux), type
</P> </P>
<PRE>make makelib <PRE>make makelib
make -f Makefile.lib foo make -f Makefile.lib foo
</PRE> </PRE>
<P>where foo is the machine name. Note that inclusion or exclusion of <P>where foo is the machine name. This kind of library is typically used
any desired optional packages should be done before typing "make to statically link a driver application to all of LAMMPS, so that you
makelib". The first "make" command will create a current Makefile.lib can insure all dependencies are satisfied at compile time. Note that
with all the file names in your src dir. The 2nd "make" command will inclusion or exclusion of any desired optional packages should be done
use it to build LAMMPS as a library. This requires that Makefile.foo before typing "make makelib". The first "make" command will create a
have a library target (lib) and system-specific settings for ARCHIVE current Makefile.lib with all the file names in your src dir. The 2nd
and ARFLAGS. See Makefile.linux for an example. The build will "make" command will use it to build LAMMPS as a static library, using
create the file liblmp_foo.a which another application can link to. the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build
will create the file liblmp_foo.a which another application can link
to.
</P> </P>
<P>When used from a C++ program, the library allows one or more LAMMPS <P>To build LAMMPS as a shared library (*.so file on Linux), which can be
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS dynamically loaded, type
</P>
<PRE>make makeshlib
make -f Makefile.shlib foo
</PRE>
<P>where foo is the machine name. This kind of library is required when
wrapping LAMMPS with Python; see <A HREF = "Section_python.html">Section_python</A>
for details. Again, note that inclusion or exclusion of any desired
optional packages should be done before typing "make makelib". The
first "make" command will create a current Makefile.shlib with all the
file names in your src dir. The 2nd "make" command will use it to
build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS
settings in src/MAKE/Makefile.foo. The build will create the file
liblmp_foo.so which another application can link to dyamically, as
well as a soft link liblmp.so, which the Python wrapper uses by
default.
</P>
<P>Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries, and be find-able by the operating system. Else you will
get a run-time error when the shared library is loaded. For LAMMPS,
this includes all libraries needed by main LAMMPS (e.g. MPI or FFTW or
JPEG), system libraries needed by main LAMMPS (e.g. extra libs needed
by MPI), or packages you have installed that require libraries
provided with LAMMPS (e.g. the USER-ATC package require
lib/atc/libatc.so) or system libraries (e.g. BLAS or Fortran-to-C
libraries) listed in the lib/package/Makefile.lammps file. See the
discussion about the LAMMPS shared library in
<A HREF = "Section_python.html">Section_python</A> for details about how to build
shared versions of these libraries, and how to insure the operating
system can find them, by setting the LD_LIBRARY_PATH environment
variable correctly.
</P>
<P>Either flavor of library allows one or more LAMMPS objects to be
instantiated from the calling program.
</P>
<P>When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from namespace; you can safely use any of its classes and methods from
within your application code, as needed. within the calling code, as needed.
</P> </P>
<P>When used from a C or Fortran program or a scripting language, the <P>When used from a C or Fortran program or a scripting language like
library has a simple function-style interface, provided in Python, the library has a simple function-style interface, provided in
src/library.cpp and src/library.h. src/library.cpp and src/library.h.
</P> </P>
<P>See the sample codes in the examples/COUPLE/simple directory as <P>See the sample codes in examples/COUPLE/simple for examples of C++ and
examples of C++ and C codes that invoke LAMMPS thru its library C codes that invoke LAMMPS thru its library interface. There are
interface. There are other examples as well in the examples/COUPLE other examples as well in the COUPLE directory which are discussed in
directory which are discussed in <A HREF = "Section_howto.html#howto_10">Section_howto <A HREF = "Section_howto.html#howto_10">Section_howto 10</A> of the manual. See
10</A> of the manual. See
<A HREF = "Section_python.html">Section_python</A> of the manual for a description <A HREF = "Section_python.html">Section_python</A> of the manual for a description
of the Python wrapper provided with LAMMPS that operates through the of the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface. LAMMPS library interface.

84
doc/Section_start.txt
View File

@ -767,37 +767,77 @@ input scripts.
2.5 Building LAMMPS as a library :h4,link(start_5) 2.5 Building LAMMPS as a library :h4,link(start_5)
LAMMPS itself can be built as a library, which can then be called from LAMMPS can be built as either a static or shared library, which can
another application or a scripting language. See "this then be called from another application or a scripting language. See
section"_Section_howto.html#howto_10 for more info on coupling LAMMPS "this section"_Section_howto.html#howto_10 for more info on coupling
to other codes. Building LAMMPS as a library is done by typing LAMMPS to other codes. See "this section"_Section_python.html for
more info on wrapping and running LAMMPS from Python.
To build LAMMPS as a static library (*.a file on Linux), type
make makelib make makelib
make -f Makefile.lib foo :pre make -f Makefile.lib foo :pre
where foo is the machine name. Note that inclusion or exclusion of where foo is the machine name. This kind of library is typically used
any desired optional packages should be done before typing "make to statically link a driver application to all of LAMMPS, so that you
makelib". The first "make" command will create a current Makefile.lib can insure all dependencies are satisfied at compile time. Note that
with all the file names in your src dir. The 2nd "make" command will inclusion or exclusion of any desired optional packages should be done
use it to build LAMMPS as a library. This requires that Makefile.foo before typing "make makelib". The first "make" command will create a
have a library target (lib) and system-specific settings for ARCHIVE current Makefile.lib with all the file names in your src dir. The 2nd
and ARFLAGS. See Makefile.linux for an example. The build will "make" command will use it to build LAMMPS as a static library, using
create the file liblmp_foo.a which another application can link to. the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build
will create the file liblmp_foo.a which another application can link
to.
When used from a C++ program, the library allows one or more LAMMPS To build LAMMPS as a shared library (*.so file on Linux), which can be
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS dynamically loaded, type
make makeshlib
make -f Makefile.shlib foo :pre
where foo is the machine name. This kind of library is required when
wrapping LAMMPS with Python; see "Section_python"_Section_python.html
for details. Again, note that inclusion or exclusion of any desired
optional packages should be done before typing "make makelib". The
first "make" command will create a current Makefile.shlib with all the
file names in your src dir. The 2nd "make" command will use it to
build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS
settings in src/MAKE/Makefile.foo. The build will create the file
liblmp_foo.so which another application can link to dyamically, as
well as a soft link liblmp.so, which the Python wrapper uses by
default.
Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries, and be find-able by the operating system. Else you will
get a run-time error when the shared library is loaded. For LAMMPS,
this includes all libraries needed by main LAMMPS (e.g. MPI or FFTW or
JPEG), system libraries needed by main LAMMPS (e.g. extra libs needed
by MPI), or packages you have installed that require libraries
provided with LAMMPS (e.g. the USER-ATC package require
lib/atc/libatc.so) or system libraries (e.g. BLAS or Fortran-to-C
libraries) listed in the lib/package/Makefile.lammps file. See the
discussion about the LAMMPS shared library in
"Section_python"_Section_python.html for details about how to build
shared versions of these libraries, and how to insure the operating
system can find them, by setting the LD_LIBRARY_PATH environment
variable correctly.
Either flavor of library allows one or more LAMMPS objects to be
instantiated from the calling program.
When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from namespace; you can safely use any of its classes and methods from
within your application code, as needed. within the calling code, as needed.
When used from a C or Fortran program or a scripting language, the When used from a C or Fortran program or a scripting language like
library has a simple function-style interface, provided in Python, the library has a simple function-style interface, provided in
src/library.cpp and src/library.h. src/library.cpp and src/library.h.
See the sample codes in the examples/COUPLE/simple directory as See the sample codes in examples/COUPLE/simple for examples of C++ and
examples of C++ and C codes that invoke LAMMPS thru its library C codes that invoke LAMMPS thru its library interface. There are
interface. There are other examples as well in the examples/COUPLE other examples as well in the COUPLE directory which are discussed in
directory which are discussed in "Section_howto "Section_howto 10"_Section_howto.html#howto_10 of the manual. See
10"_Section_howto.html#howto_10 of the manual. See
"Section_python"_Section_python.html of the manual for a description "Section_python"_Section_python.html of the manual for a description
of the Python wrapper provided with LAMMPS that operates through the of the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface. LAMMPS library interface.