Python 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 +together, e.g. to run a coupled or multiscale model. See Section section of the manual and the couple directory of the distribution for more ideas about coupling LAMMPS to other codes. See Section_start 4 about -how to build LAMMPS as a library, and this -section for a description of the library +how to build LAMMPS as a library, and Section_howto +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. @@ -61,7 +61,9 @@ LAMMPS thru Python will be negligible.
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 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) "ctypes" package in Python, which auto-generates the interface code @@ -99,18 +101,11 @@ the following section.
setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/src-
Note that a LAMMPS build may depend on several auxiliary libraries, -which are specied 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, you may -pre-build additional libraries in the lib directories, which are linked -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. +
As discussed below, if your LAMMPS build includes auxiliary libraries, +they must also 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 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 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, a popular open-source version of MPI, distributed -by Argonne National Labs. From within the mpich directory, type +
Instructions on how to build LAMMPS as a shared library are given in +Section_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. +
+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. +
+For example, here is how to build and install the MPICH +library, a popular open-source version of MPI, distributed by +Argonne National Labs, as a shared library in the default +/usr/local/lib location:
@@ -139,53 +168,23 @@ by Argonne National Labs. From within the mpich directory, type make make install -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. +
You may need to use "sudo make install" in place of the last line if +you do not have write priveleges for /usr/local/lib. The end result +should be the file /usr/local/lib/libmpich.so.
-Before proceeding, there are 2 items to note. +
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.
-(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 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. -
-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. +
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 +make MPI calls directly from Python in your script, if you desire.
There are several Python packages available that purport to wrap MPI 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.
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 +This means Python 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 +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. +LAMMPS in parallel and MPI calls themselves from a Python script which +is itself running in parallel. However, when I downloaded and looked +at a few of them, their documentation 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 be installed in your Python. After launching python, type
->>> import numpy +import numpyto 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 @@ -244,58 +243,108 @@ 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 +import pyparwithout error. You should also be able to run python in parallel on a simple test script
-% mpirun -np 4 python test.script +% mpirun -np 4 python test.py-where test.script contains the lines +
where test.py contains the lines
import pypar print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())-and see one line of output for each processor you ran on. +
and see one line of output for each processor you run on.
11.4 Testing the Python-LAMMPS interface
-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 >>> lmp = lammps()If you get no errors, you're ready to use LAMMPS from Python. +If the load fails, the most common error to see is
-% mpirun -np 4 python test.script +"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. 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. +
+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 carefully. +
+Test LAMMPS and Python in serial: +
+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")-where test.script contains the lines +
Or put the same lines in the file test.py and run it as +
+% python test.py ++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 ++Test LAMMPS and Python in parallel: +
+To run LAMMPS in parallel, assuming you have installed the +Pypar package as discussed +above, create a test.py file containing these lines:
import pypar from lammps import 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()-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, -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. +
% mpirun -np 4 python test.py ++and you should see the same output as if you had typed
-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. +
% mpirun -np 4 lmp_g++ < in.lj ++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 a Python script can be invoked in one of several ways: +
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 -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 "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: +the "lammps" module in your Python script. You can also include its +settings as follows, which are useful in test return values from some +of the methods described below:
from lammps import lammps 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 C or Fortran program. -lmp = lammps() # create a LAMMPS object -lmp = lammps(list) # ditto, with command-line args, list = ["-echo","screen"] +lmp = lammps() # create a LAMMPS object using the default liblmp.so library +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)lmp.close() # destroy a LAMMPS object@@ -352,16 +404,16 @@ lmp = lammps(list) # ditto, with command-line args, list = ["-echo","scree lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100"xlo = lmp.extract_global(name,type) # extract a global quantity - # name = "boxxlo", "nlocal", etc + # name = "boxxlo", "nlocal", etc # type = INT or DOUBLEcoords = lmp.extract_atom(name,type) # extract a per-atom quantity - # name = "x", "type", etc + # name = "x", "type", etc # type = IPTR or DPTR or DPTRPTReng = 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 + # id = ID of compute or fix # style = 0 = global data # 1 = per-atom data # 2 = local data @@ -382,12 +434,23 @@ lmp.put_coords(x) # set all atom coords via x
-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. +
IMPORTANT NOTE: Currenlty, 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 know how to do it from Pypar. So for now, it +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") +The file() and command() methods allow an input script or single commands to be invoked.
@@ -497,15 +560,10 @@ following steps:
LAMMPS itself can be built as a library, which can then be called from -another application or a scripting language. See this -section for more info on coupling LAMMPS -to other codes. Building LAMMPS as a library is done by typing +
LAMMPS can be built as either a static or shared library, which can +then be called from another application or a scripting language. See +this section for more info on coupling +LAMMPS to other codes. See this section 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 -f Makefile.lib foo-
where foo is the machine name. 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.lib -with all the file names in your src dir. The 2nd "make" command will -use it to build LAMMPS as a library. This requires that Makefile.foo -have a library target (lib) and system-specific settings for ARCHIVE -and ARFLAGS. See Makefile.linux for an example. The build will -create the file liblmp_foo.a which another application can link to. +
where foo is the machine name. This kind of library is typically used +to statically link a driver application to all of LAMMPS, so that you +can insure all dependencies are satisfied at compile time. 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.lib with all the file names in your src dir. The 2nd +"make" command will use it to build LAMMPS as a static library, using +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 -objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS +
To build LAMMPS as a shared library (*.so file on Linux), which can be +dynamically loaded, type +
+make makeshlib +make -f Makefile.shlib foo ++
where foo is the machine name. This kind of library is required when +wrapping LAMMPS with Python; see Section_python +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 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 -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 -library has a simple function-style interface, provided in +
When used from a C or Fortran program or a scripting language like +Python, the library has a simple function-style interface, provided in src/library.cpp and src/library.h.
-See the sample codes in the examples/COUPLE/simple directory as -examples of C++ and C codes that invoke LAMMPS thru its library -interface. There are other examples as well in the examples/COUPLE -directory which are discussed in Section_howto -10 of the manual. See +
See the sample codes in examples/COUPLE/simple for 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 +Section_howto 10 of the manual. See Section_python of the manual for a description of the Python wrapper provided with LAMMPS that operates through the LAMMPS library interface. diff --git a/doc/Section_start.txt b/doc/Section_start.txt index ff28bf4285..4688b8d437 100644 --- a/doc/Section_start.txt +++ b/doc/Section_start.txt @@ -767,37 +767,77 @@ input scripts. 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 -another application or a scripting language. See "this -section"_Section_howto.html#howto_10 for more info on coupling LAMMPS -to other codes. Building LAMMPS as a library is done by typing +LAMMPS can be built as either a static or shared library, which can +then be called from another application or a scripting language. See +"this section"_Section_howto.html#howto_10 for more info on coupling +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 -f Makefile.lib foo :pre -where foo is the machine name. 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.lib -with all the file names in your src dir. The 2nd "make" command will -use it to build LAMMPS as a library. This requires that Makefile.foo -have a library target (lib) and system-specific settings for ARCHIVE -and ARFLAGS. See Makefile.linux for an example. The build will -create the file liblmp_foo.a which another application can link to. +where foo is the machine name. This kind of library is typically used +to statically link a driver application to all of LAMMPS, so that you +can insure all dependencies are satisfied at compile time. 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.lib with all the file names in your src dir. The 2nd +"make" command will use it to build LAMMPS as a static library, using +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 -objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS +To build LAMMPS as a shared library (*.so file on Linux), which can be +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 -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 -library has a simple function-style interface, provided in +When used from a C or Fortran program or a scripting language like +Python, the library has a simple function-style interface, provided in src/library.cpp and src/library.h. -See the sample codes in the examples/COUPLE/simple directory as -examples of C++ and C codes that invoke LAMMPS thru its library -interface. There are other examples as well in the examples/COUPLE -directory which are discussed in "Section_howto -10"_Section_howto.html#howto_10 of the manual. See +See the sample codes in examples/COUPLE/simple for 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 +"Section_howto 10"_Section_howto.html#howto_10 of the manual. See "Section_python"_Section_python.html of the manual for a description of the Python wrapper provided with LAMMPS that operates through the LAMMPS library interface.