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@8605 f3b2605a-c512-4ea7-a41b-209d697bcdaa

Browse Source
This commit is contained in:
sjplimp
2012-08-11 19:06:25 +00:00
parent 58443251c3
commit 01b7ac9e20
56 changed files with 116 additions and 6388 deletions
Download Patch File Download Diff File Expand all files Collapse all files

306
doc/Section_python.txt
View File

@ -11,19 +11,22 @@
This section describes how to build and use LAMMPS via a Python
interface.
11.1 "Extending Python with a serial version of LAMMPS"_#py_1
11.2 "Creating a shared MPI library"_#py_2
11.3 "Extending Python with a parallel version of LAMMPS"_#py_3
11.4 "Extending Python with MPI"_#py_4
11.5 "Testing the Python-LAMMPS interface"_#py_5
11.6 "Using LAMMPS from Python"_#py_6
11.7 "Example Python scripts that use LAMMPS"_#py_7 :ul
11.1 "Setting necessary environment variables"_#py_1
11.2 "Building LAMMPS as a shared library"_#py_2
11.3 "Extending Python with MPI"_#py_3
11.4 "Testing the Python-LAMMPS interface"_#py_4
11.5 "Using LAMMPS from Python"_#py_5
11.6 "Example Python scripts that use LAMMPS"_#py_6 :ul
The LAMMPS distribution includes some Python code in its python
directory which wraps the library interface to LAMMPS. This makes it
is possible to run LAMMPS, invoke LAMMPS commands or give it an input
script, extract LAMMPS results, an modify internal LAMMPS variables,
either from a Python script or interactively from a Python prompt.
The LAMMPS distribution includes the file python/lammps.py which wraps
the library interface to LAMMPS. This file makes it is possible to
run LAMMPS, invoke LAMMPS commands or give it an input script, extract
LAMMPS results, an modify internal LAMMPS variables, either from a
Python script or interactively from a Python prompt. You can do the
former in serial or parallel. Running Python interactively in
parallel does not generally work, unless you have a package installed
that extends your Python to enable multiple instances of Python to
read what you type.
"Python"_http://www.python.org is a powerful scripting and programming
language which can be used to wrap software like LAMMPS and other
@ -37,75 +40,116 @@ section"_Section_howto.html#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.
This has the effect of extending the Python inteface as well. See
details below.
This can easily extend the Python inteface as well. See details
below.
By using the Python interface LAMMPS can also be coupled with a GUI or
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.
By using the Python interface, LAMMPS can also be coupled with a GUI
or other visualization tools that display graphs or animations in real
time as LAMMPS runs. Examples of such scripts are inlcluded in the
python directory.
Two advantages of using Python are how concise the language is and
Two advantages of using Python are how concise the language is, and
that it can be run interactively, enabling rapid development and
debugging of programs. If you use it to mostly invoke costly
operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.
Before using LAMMPS from a Python script, the Python on your machine
must be "extended" to include an interface to the LAMMPS library. If
your Python script will invoke MPI operations, you will also need to
extend your Python with an interface to MPI itself.
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.
Thus you should first decide how you intend to use LAMMPS from Python.
There are 3 options:
The Python wrapper for LAMMPS uses the amazing and magical (to me)
"ctypes" package in Python, which auto-generates the interface code
needed between Python and a set of C interface routines for a library.
Ctypes is part of standard Python for versions 2.5 and later. You can
check which version of Python you have installed, by simply typing
"python" at a shell prompt.
(1) Use LAMMPS on a single processor running Python.
:line
:line
(2) Use LAMMPS in parallel, where each processor runs Python, but your
Python program does not use MPI.
11.1 Setting necessary environment variables :link(py_1),h4
(3) Use LAMMPS in parallel, where each processor runs Python, and your
Python script also makes MPI calls through a Python/MPI interface.
For Python to use the LAMMPS interface, it needs to find two files.
The paths to these files need to be added to two environment variables
that Python checks.
Note that for (2) and (3) you will not be able to use Python
interactively by typing commands and getting a response. This is
because you will have multiple instances of Python running (e.g. on a
parallel machine) and they cannot all read what you type.
The first is the environment variable PYTHONPATH. It needs
to include the directory where the python/lammps.py file is.
For the csh or tcsh shells, you could add something like this to your
~/.cshrc file:
setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python :pre
The second is the environment variable LD_LIBRARY_PATH, which is used
by the operating system to find dynamic shared libraries when it loads
them. It needs to include the directory where the shared LAMMPS
library will be. Normally this is the LAMMPS src dir, as explained in
the following section.
For the csh or tcsh shells, you could add something like this to your
~/.cshrc file:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
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.
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:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src/STUBS :pre
If you are using the LAMMPS USER-ATC package, you need to add
something like this to your ~/.cshrc file:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/atc :pre
:line
11.2 Building LAMMPS as a shared library :link(py_2),h4
A shared library is one that is dynamically loadable, which is what
Python requires. On Linux this is a library file that ends in ".so",
not ".a". Such a shared library is normally not built if you
installed MPI yourself, but it is easy to do. Here is how to do it
for "MPICH"_mpich, a popular open-source version of MPI, distributed
by Argonne National Labs. From within the mpich directory, type
:link(mpich,http://www-unix.mcs.anl.gov/mpi)
./configure --enable-shared
make
make install :pre
You may need to use "sudo make install" in place of the last line.
The end result should be the file libmpich.so in /usr/local/lib.
Working in mode (1) does not require your machine to have MPI
installed. You should extend your Python with a serial version of
LAMMPS and the dummy MPI library provided with LAMMPS. See
instructions below on how to do this.
Working in mode (2) requires your machine to have an MPI library
installed, but your Python does not need to be extended with MPI
itself. The MPI library must be a shared library (e.g. a *.so file on
Linux) which is not typically created when MPI is built/installed.
See instruction below on how to do this. You should extend your
Python with the a parallel versionn of LAMMPS which will use the
shared MPI system library. See instructions below on how to do this.
Working in mode (3) requires your machine to have MPI installed (as a
shared library as in (2)). You must also extend your Python with a
parallel version of LAMMPS (same as in (2)) and with MPI itself, via
one of several available Python/MPI packages. See instructions below
on how to do the latter task.
Several of the following sub-sections cover the rest of the Python
setup discussion. The next to last sub-section describes the Python
syntax used to invoke LAMMPS. The last sub-section describes example
Python scripts included in the python directory.
Before proceeding, there are 2 items to note.
(1) The provided Python wrapper for LAMMPS uses the amazing and
magical (to me) "ctypes" package in Python, which auto-generates the
interface code needed between Python and a set of C interface routines
for a library. Ctypes is part of standard Python for versions 2.5 and
later. You can check which version of Python you have installed, by
simply typing "python" at a shell prompt.
(2) Any library wrapped by Python, including LAMMPS, must be built as
a shared library (e.g. a *.so file on Linux and not a *.a file). The
python/setup_serial.py and setup.py scripts do this build for LAMMPS
@ -131,63 +175,6 @@ will also require you to edit the python/setup_serial.py or setup.py
scripts to enable Python to access those libraries when it builds the
LAMMPS wrapper.
:line
:line
11.1 Extending Python with a serial version of LAMMPS :link(py_1),h4
From the python directory in the LAMMPS distribution, type
python setup_serial.py build :pre
and then one of these commands:
sudo python setup_serial.py install
python setup_serial.py install --home=~/foo :pre
The "build" command should compile all the needed LAMMPS files,
including its dummy MPI library. The first "install" command will put
the needed files in your Python's site-packages sub-directory, so that
Python can load them. For example, if you installed Python yourself
on a Linux machine, it would typically be somewhere like
/usr/local/lib/python2.5/site-packages. Installing Python packages
this way often requires you to be able to write to the Python
directories, which may require root priveleges, hence the "sudo"
prefix. If this is not the case, you can drop the "sudo". If you use
the "sudo" prefix and you have installed Python yourself, you should
make sure that root uses the same Python as the one you did the
"install" in. E.g. these 2 commands may do the install in different
Python versions:
python setup_serial.py install --home=~/foo
python /usr/local/bin/python/setup_serial.py install --home=~/foo :pre
Alternatively, you can install the LAMMPS files (or any other Python
packages) in your own user space. The second "install" command does
this, where you should replace "foo" with your directory of choice.
If these commands are successful, a {lammps.py} and
{_lammps_serial.so} file will be put in the appropriate directory.
:line
11.2 Creating a shared MPI library :link(py_2),h4
A shared library is one that is dynamically loadable, which is what
Python requires. On Linux this is a library file that ends in ".so",
not ".a". Such a shared library is normally not built if you
installed MPI yourself, but it is easy to do. Here is how to do it
for "MPICH"_mpich, a popular open-source version of MPI, distributed
by Argonne National Labs. From within the mpich directory, type
:link(mpich,http://www-unix.mcs.anl.gov/mpi)
./configure --enable-shared
make
make install :pre
You may need to use "sudo make install" in place of the last line.
The end result should be the file libmpich.so in /usr/local/lib.
IMPORTANT NOTE: If the file libmpich.a already exists in your
installation directory (e.g. /usr/local/lib), you will now have both a
@ -200,47 +187,16 @@ 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.
:line
11.3 Extending Python with MPI :link(py_3),h4
11.3 Extending Python with a parallel version of LAMMPS :link(py_3),h4
From the python directory, type
python setup.py build :pre
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.
and then one of these commands:
sudo python setup.py install
python setup.py install --home=~/foo :pre
The "build" command should compile all the needed LAMMPS C++ files,
which will require MPI to be installed on your system. This means it
must find both the header file mpi.h and a shared library file,
e.g. libmpich.so if the MPICH version of MPI is installed. See the
preceding section for how to create a shared library version of MPI if
it does not exist. You may need to adjust the "include_dirs" and
"library_dirs" and "libraries" fields in python/setup.py to
insure the Python build finds all the files it needs.
The first "install" command will put the needed files in your Python's
site-packages sub-directory, so that Python can load them. For
example, if you installed Python yourself on a Linux machine, it would
typically be somewhere like /usr/local/lib/python2.5/site-packages.
Installing Python packages this way often requires you to be able to
write to the Python directories, which may require root priveleges,
hence the "sudo" prefix. If this is not the case, you can drop the
"sudo".
Alternatively, you can install the LAMMPS files (or any other Python
packages) in your own user space. The second "install" command does
this, where you should replace "foo" with your directory of choice.
If these commands are successful, a {lammps.py} and {_lammps.so} file
will be put in the appropriate directory.
:line
11.4 Extending Python with MPI :link(py_4),h4
There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python.
@ -315,37 +271,16 @@ and see one line of output for each processor you ran on.
:line
11.5 Testing the Python-LAMMPS interface :link(py_5),h4
11.4 Testing the Python-LAMMPS interface :link(py_4),h4
Before using LAMMPS in a Python program, one more step is needed. The
interface to LAMMPS is via the Python ctypes package, which loads the
shared LAMMPS library via a CDLL() call, which in turn is a wrapper on
the C-library dlopen(). This command is different than a normal
Python "import" and needs to be able to find the LAMMPS shared
library, which is either in the Python site-packages directory or in a
local directory you specified in the "python setup.py install"
command, as described above.
The simplest way to do this is add a line like this to your
.cshrc or other shell start-up file.
setenv LD_LIBRARY_PATH
$\{LD_LIBRARY_PATH\}:/usr/local/lib/python2.5/site-packages :pre
and then execute the shell file to insure the path has been updated.
This will extend the path that dlopen() uses to look for shared
libraries.
To test if the serial LAMMPS library has been successfully installed
(mode 1 above), launch Python and type
To test if LAMMPS is now callable from Python, launch Python and type:
>>> from lammps import lammps
>>> lmp = lammps() :pre
If you get no errors, you're ready to use serial LAMMPS from Python.
If you get no errors, you're ready to use LAMMPS from Python.
If you built LAMMPS for parallel use (mode 2 or 3 above), launch
Python in parallel:
% mpirun -np 4 python test.script :pre
@ -368,15 +303,6 @@ see if the LAMMPS run says it ran on P processors or if you get output
from P duplicated 1-processor runs written to the screen. In the
latter case, Pypar is not working correctly.
Note that this line:
from lammps import lammps :pre
will import either the serial or parallel version of the LAMMPS
library, as wrapped by lammps.py. But if you installed both via
setup_serial.py and setup.py, it will always import the parallel
version, since it attempts that first.
Note that if your Python script imports the Pypar package (as above),
so that it can use MPI calls directly, then Pypar initializes MPI for
you. Thus the last line of your Python script should be
@ -408,7 +334,7 @@ Python on a single processor, not in parallel.
:line
:line
11.6 Using LAMMPS from Python :link(py_6),h4
11.5 Using LAMMPS from Python :link(py_5),h4
The Python interface to LAMMPS consists of a Python "lammps" module,
the source code for which is in python/lammps.py, which creates a
@ -599,7 +525,7 @@ Python script. Isn't ctypes amazing? :l,ule
:line
:line
11.7 Example Python scripts that use LAMMPS :link(py_7),h4
11.6 Example Python scripts that use LAMMPS :link(py_6),h4
These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of