From 45ccb34ac32da5a51f5a7d005e00f48c8387edfb Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Sat, 11 Aug 2012 19:17:43 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8612
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/Section_howto.html  |  15 +-
 doc/Section_python.html | 303 ++++++++++++++--------------------------
 doc/Section_start.html  |  16 +--
 3 files changed, 122 insertions(+), 212 deletions(-)

diff --git a/doc/Section_howto.html b/doc/Section_howto.html
index ea4e93f11c..2d9cca3028 100644
--- a/doc/Section_howto.html
+++ b/doc/Section_howto.html
@@ -659,8 +659,8 @@ invoked with minimal overhead (no setup or clean-up) if you wish to do
 multiple short runs, driven by another program.
 </P>
 <P>Examples of driver codes that call LAMMPS as a library are included in
-the "couple" directory of the LAMMPS distribution; see couple/README
-for more details:
+the examples/COUPLE directory of the LAMMPS distribution; see
+examples/COUPLE/README for more details:
 </P>
 <UL><LI>simple: simple driver programs in C++ and C which invoke LAMMPS as a
 library 
@@ -1820,11 +1820,12 @@ details.
 <P>The key idea of the library interface is that you can write any
 functions you wish to define how your code talks to LAMMPS and add
 them to src/library.cpp and src/library.h, as well as to the <A HREF = "Section_python.html">Python
-interface</A>.  The routines you add can access
-or change any LAMMPS data you wish.  The couple and python directories
-have example C++ and C and Python codes which show how a driver code
-can link to LAMMPS as a library, run LAMMPS on a subset of processors,
-grab data from LAMMPS, change it, and put it back into LAMMPS.
+interface</A>.  The routines you add can access or
+change any LAMMPS data you wish.  The examples/COUPLE and python
+directories have example C++ and C and Python codes which show how a
+driver code can link to LAMMPS as a library, run LAMMPS on a subset of
+processors, grab data from LAMMPS, change it, and put it back into
+LAMMPS.
 </P>
 <HR>
 
diff --git a/doc/Section_python.html b/doc/Section_python.html
index e8b768c5d8..0a577bccec 100644
--- a/doc/Section_python.html
+++ b/doc/Section_python.html
@@ -14,19 +14,22 @@
 <P>This section describes how to build and use LAMMPS via a Python
 interface.
 </P>
-<UL><LI>11.1 <A HREF = "#py_1">Extending Python with a serial version of LAMMPS</A>
-<LI>11.2 <A HREF = "#py_2">Creating a shared MPI library</A>
-<LI>11.3 <A HREF = "#py_3">Extending Python with a parallel version of LAMMPS</A>
-<LI>11.4 <A HREF = "#py_4">Extending Python with MPI</A>
-<LI>11.5 <A HREF = "#py_5">Testing the Python-LAMMPS interface</A>
-<LI>11.6 <A HREF = "#py_6">Using LAMMPS from Python</A>
-<LI>11.7 <A HREF = "#py_7">Example Python scripts that use LAMMPS</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.3 <A HREF = "#py_3">Extending Python with MPI</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.6 <A HREF = "#py_6">Example Python scripts that use LAMMPS</A> 
 </UL>
-<P>The LAMMPS distribution includes some Python code in its python
-directory which wraps the library interface to LAMMPS.  This makes it
-is possible to run LAMMPS, invoke LAMMPS commands or give it an input
-script, extract LAMMPS results, an modify internal LAMMPS variables,
-either from a Python script or interactively from a Python prompt.
+<P>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.
 </P>
 <P><A HREF = "http://www.python.org">Python</A> is a powerful scripting and programming
 language which can be used to wrap software like LAMMPS and other
@@ -40,75 +43,107 @@ section</A> for a description of the library
 interface provided in src/library.cpp and src/library.h and how to
 extend it for your needs.  As described below, that interface is what
 is exposed to Python.  It is designed to be easy to add functions to.
-This has the effect of extending the Python inteface as well.  See
-details below.
+This can easily extend the Python inteface as well.  See details
+below.
 </P>
-<P>By using the Python interface LAMMPS can also be coupled with a GUI or
-visualization tools that display graphs or animations in real time as
-LAMMPS runs.  Examples of such scripts are inlcluded in the python
-directory.
+<P>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.
 </P>
-<P>Two advantages of using Python are how concise the language is and
+<P>Two advantages of using Python are how concise the language is, and
 that it can be run interactively, enabling rapid development and
 debugging of programs.  If you use it to mostly invoke costly
 operations within LAMMPS, such as running a simulation for a
 reasonable number of timesteps, then the overhead cost of invoking
 LAMMPS thru Python will be negligible.
 </P>
-<P>Before using LAMMPS from a Python script, the Python on your machine
-must be "extended" to include an interface to the LAMMPS library.  If
-your Python script will invoke MPI operations, you will also need to
-extend your Python with an interface to MPI itself.
+<P>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.
 </P>
-<P>Thus you should first decide how you intend to use LAMMPS from Python.
-There are 3 options:
+<P>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.
 </P>
-<P>(1) Use LAMMPS on a single processor running Python.
+<HR>
+
+<HR>
+
+<A NAME = "py_1"></A><H4>11.1 Setting necessary environment variables 
+</H4>
+<P>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.
 </P>
-<P>(2) Use LAMMPS in parallel, where each processor runs Python, but your
-Python program does not use MPI.
+<P>The first is the environment variable PYTHONPATH.  It needs
+to include the directory where the python/lammps.py file is.
 </P>
-<P>(3) Use LAMMPS in parallel, where each processor runs Python, and your
-Python script also makes MPI calls through a Python/MPI interface.
+<P>For the csh or tcsh shells, you could add something like this to your
+~/.cshrc file:
 </P>
-<P>Note that for (2) and (3) you will not be able to use Python
-interactively by typing commands and getting a response.  This is
-because you will have multiple instances of Python running (e.g. on a
-parallel machine) and they cannot all read what you type.
+<PRE>setenv PYTHONPATH $<I>PYTHONPATH</I>:/home/sjplimp/lammps/python 
+</PRE>
+<P>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.
 </P>
-<P>Working in mode (1) does not require your machine to have MPI
-installed.  You should extend your Python with a serial version of
-LAMMPS and the dummy MPI library provided with LAMMPS.  See
-instructions below on how to do this.
+<P>For the csh or tcsh shells, you could add something like this to your
+~/.cshrc file:
 </P>
-<P>Working in mode (2) requires your machine to have an MPI library
-installed, but your Python does not need to be extended with MPI
-itself.  The MPI library must be a shared library (e.g. a *.so file on
-Linux) which is not typically created when MPI is built/installed.
-See instruction below on how to do this.  You should extend your
-Python with the a parallel versionn of LAMMPS which will use the
-shared MPI system library.  See instructions below on how to do this.
+<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src 
+</PRE>
+<P>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.
 </P>
-<P>Working in mode (3) requires your machine to have MPI installed (as a
-shared library as in (2)).  You must also extend your Python with a
-parallel version of LAMMPS (same as in (2)) and with MPI itself, via
-one of several available Python/MPI packages.  See instructions below
-on how to do the latter task.
+<P>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>Several of the following sub-sections cover the rest of the Python
-setup discussion.  The next to last sub-section describes the Python
-syntax used to invoke LAMMPS.  The last sub-section describes example
-Python scripts included in the python directory.
+<P>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:
+</P>
+<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src/STUBS 
+</PRE>
+<P>If you are using the LAMMPS USER-ATC package, you need to add
+something like this to your ~/.cshrc file:
+</P>
+<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/lib/atc 
+</PRE>
+<HR>
+
+<A NAME = "py_2"></A><H4>11.2 Building LAMMPS as a shared library 
+</H4>
+<P>A shared library is one that is dynamically loadable, which is what
+Python requires.  On Linux this is a library file that ends in ".so",
+not ".a".  Such a shared library is normally not built if you
+installed MPI yourself, but it is easy to do.  Here is how to do it
+for <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH</A>, a popular open-source version of MPI, distributed
+by Argonne National Labs.  From within the mpich directory, type
+</P>
+
+
+<PRE>./configure --enable-shared
+make
+make install 
+</PRE>
+<P>You may need to use "sudo make install" in place of the last line.
+The end result should be the file libmpich.so in /usr/local/lib.
 </P>
 <P>Before proceeding, there are 2 items to note.
 </P>
-<P>(1) The provided Python wrapper for LAMMPS uses the amazing and
-magical (to me) "ctypes" package in Python, which auto-generates the
-interface code needed between Python and a set of C interface routines
-for a library.  Ctypes is part of standard Python for versions 2.5 and
-later.  You can check which version of Python you have installed, by
-simply typing "python" at a shell prompt.
-</P>
 <P>(2) Any library wrapped by Python, including LAMMPS, must be built as
 a shared library (e.g. a *.so file on Linux and not a *.a file).  The
 python/setup_serial.py and setup.py scripts do this build for LAMMPS
@@ -134,65 +169,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.
 </P>
-<HR>
-
-<HR>
-
-<A NAME = "py_1"></A><H4>11.1 Extending Python with a serial version of LAMMPS 
-</H4>
-<P>From the python directory in the LAMMPS distribution, type
-</P>
-<PRE>python setup_serial.py build 
-</PRE>
-<P>and then one of these commands:
-</P>
-<PRE>sudo python setup_serial.py install
-python setup_serial.py install --home=~/foo 
-</PRE>
-<P>The "build" command should compile all the needed LAMMPS files,
-including its dummy MPI library.  The first "install" command will put
-the needed files in your Python's site-packages sub-directory, so that
-Python can load them.  For example, if you installed Python yourself
-on a Linux machine, it would typically be somewhere like
-/usr/local/lib/python2.5/site-packages.  Installing Python packages
-this way often requires you to be able to write to the Python
-directories, which may require root priveleges, hence the "sudo"
-prefix.  If this is not the case, you can drop the "sudo".  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:
-</P>
-<PRE>python setup_serial.py install --home=~/foo
-python /usr/local/bin/python/setup_serial.py install --home=~/foo 
-</PRE>
-<P>Alternatively, you can install the LAMMPS files (or any other Python
-packages) in your own user space.  The second "install" command does
-this, where you should replace "foo" with your directory of choice.
-</P>
-<P>If these commands are successful, a <I>lammps.py</I> and
-<I>_lammps_serial.so</I> file will be put in the appropriate directory.
-</P>
-<HR>
-
-<A NAME = "py_2"></A><H4>11.2 Creating a shared MPI library 
-</H4>
-<P>A shared library is one that is dynamically loadable, which is what
-Python requires.  On Linux this is a library file that ends in ".so",
-not ".a".  Such a shared library is normally not built if you
-installed MPI yourself, but it is easy to do.  Here is how to do it
-for <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH</A>, a popular open-source version of MPI, distributed
-by Argonne National Labs.  From within the mpich directory, type
-</P>
-
-
-<PRE>./configure --enable-shared
-make
-make install 
-</PRE>
-<P>You may need to use "sudo make install" in place of the last line.
-The end result should be the file libmpich.so in /usr/local/lib.
-</P>
 <P>IMPORTANT NOTE: If the file libmpich.a already exists in your
 installation directory (e.g. /usr/local/lib), you will now have both a
 static and shared MPI library.  This will be fine for running LAMMPS
@@ -204,48 +180,13 @@ 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>
-<HR>
-
-<A NAME = "py_3"></A><H4>11.3 Extending Python with a parallel version of LAMMPS 
+<A NAME = "py_3"></A><H4>11.3 Extending Python with MPI 
 </H4>
-<P>From the python directory, type
+<P>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.
 </P>
-<PRE>python setup.py build 
-</PRE>
-<P>and then one of these commands:
-</P>
-<PRE>sudo python setup.py install
-python setup.py install --home=~/foo 
-</PRE>
-<P>The "build" command should compile all the needed LAMMPS C++ files,
-which will require MPI to be installed on your system.  This means it
-must find both the header file mpi.h and a shared library file,
-e.g. libmpich.so if the MPICH version of MPI is installed.  See the
-preceding section for how to create a shared library version of MPI if
-it does not exist.  You may need to adjust the "include_dirs" and
-"library_dirs" and "libraries" fields in python/setup.py to
-insure the Python build finds all the files it needs.
-</P>
-<P>The first "install" command will put the needed files in your Python's
-site-packages sub-directory, so that Python can load them.  For
-example, if you installed Python yourself on a Linux machine, it would
-typically be somewhere like /usr/local/lib/python2.5/site-packages.
-Installing Python packages this way often requires you to be able to
-write to the Python directories, which may require root priveleges,
-hence the "sudo" prefix.  If this is not the case, you can drop the
-"sudo".
-</P>
-<P>Alternatively, you can install the LAMMPS files (or any other Python
-packages) in your own user space.  The second "install" command does
-this, where you should replace "foo" with your directory of choice.
-</P>
-<P>If these commands are successful, a <I>lammps.py</I> and <I>_lammps.so</I> file
-will be put in the appropriate directory.
-</P>
-<HR>
-
-<A NAME = "py_4"></A><H4>11.4 Extending Python with MPI 
-</H4>
 <P>There are several Python packages available that purport to wrap MPI
 as a library and allow MPI functions to be called from Python.
 </P>
@@ -319,37 +260,14 @@ print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())
 </P>
 <HR>
 
-<A NAME = "py_5"></A><H4>11.5 Testing the Python-LAMMPS interface 
+<A NAME = "py_4"></A><H4>11.4 Testing the Python-LAMMPS interface 
 </H4>
-<P>Before using LAMMPS in a Python program, one more step is needed.  The
-interface to LAMMPS is via the Python ctypes package, which loads the
-shared LAMMPS library via a CDLL() call, which in turn is a wrapper on
-the C-library dlopen().  This command is different than a normal
-Python "import" and needs to be able to find the LAMMPS shared
-library, which is either in the Python site-packages directory or in a
-local directory you specified in the "python setup.py install"
-command, as described above.
-</P>
-<P>The simplest way to do this is add a line like this to your
-.cshrc or other shell start-up file.
-</P>
-<PRE>setenv LD_LIBRARY_PATH
-${LD_LIBRARY_PATH}:/usr/local/lib/python2.5/site-packages 
-</PRE>
-<P>and then execute the shell file to insure the path has been updated.
-This will extend the path that dlopen() uses to look for shared
-libraries.
-</P>
-<P>To test if the serial LAMMPS library has been successfully installed
-(mode 1 above), launch Python and type
+<P>To test if LAMMPS is now callable from Python, launch Python and type:
 </P>
 <PRE>>>> from lammps import lammps
 >>> lmp = lammps() 
 </PRE>
-<P>If you get no errors, you're ready to use serial LAMMPS from Python.
-</P>
-<P>If you built LAMMPS for parallel use (mode 2 or 3 above), launch
-Python in parallel:
+<P>If you get no errors, you're ready to use LAMMPS from Python.
 </P>
 <PRE>% mpirun -np 4 python test.script 
 </PRE>
@@ -372,15 +290,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.
 </P>
-<P>Note that this line:
-</P>
-<PRE>from lammps import lammps 
-</PRE>
-<P>will import either the serial or parallel version of the LAMMPS
-library, as wrapped by lammps.py.  But if you installed both via
-setup_serial.py and setup.py, it will always import the parallel
-version, since it attempts that first.
-</P>
 <P>Note that if your Python script imports the Pypar package (as above),
 so that it can use MPI calls directly, then Pypar initializes MPI for
 you.  Thus the last line of your Python script should be
@@ -413,7 +322,7 @@ Python on a single processor, not in parallel.
 
 <HR>
 
-<A NAME = "py_6"></A><H4>11.6 Using LAMMPS from Python 
+<A NAME = "py_5"></A><H4>11.5 Using LAMMPS from Python 
 </H4>
 <P>The Python interface to LAMMPS consists of a Python "lammps" module,
 the source code for which is in python/lammps.py, which creates a
@@ -605,7 +514,7 @@ Python script.  Isn't ctypes amazing?
 
 <HR>
 
-<A NAME = "py_7"></A><H4>11.7 Example Python scripts that use LAMMPS 
+<A NAME = "py_6"></A><H4>11.6 Example Python scripts that use LAMMPS 
 </H4>
 <P>These are the Python scripts included as demos in the python/examples
 directory of the LAMMPS distribution, to illustrate the kinds of
diff --git a/doc/Section_start.html b/doc/Section_start.html
index eef8e51a83..93c3d6aabd 100644
--- a/doc/Section_start.html
+++ b/doc/Section_start.html
@@ -44,7 +44,6 @@ sub-directories:
 <TR><TD >README</TD><TD > text file</TD></TR>
 <TR><TD >LICENSE</TD><TD > the GNU General Public License (GPL)</TD></TR>
 <TR><TD >bench</TD><TD > benchmark problems</TD></TR>
-<TR><TD >couple</TD><TD > code coupling examples, using LAMMPS as a library</TD></TR>
 <TR><TD >doc</TD><TD > documentation</TD></TR>
 <TR><TD >examples</TD><TD > simple test problems</TD></TR>
 <TR><TD >potentials</TD><TD > embedded atom method (EAM) potential files</TD></TR>
@@ -800,13 +799,14 @@ within your application code, as needed.
 library has a simple function-style interface, provided in
 src/library.cpp and src/library.h.
 </P>
-<P>See the sample codes couple/simple/simple.cpp and simple.c as examples
-of C++ and C codes that invoke LAMMPS thru its library interface.
-There are other examples as well in the couple directory which are
-discussed in <A HREF = "Section_howto.html#howto_10">Section_howto 10</A> of the
-manual.  See <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 LAMMPS library interface.
+<P>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 <A HREF = "Section_howto.html#howto_10">Section_howto
+10</A> of the manual.  See
+<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
+LAMMPS library interface.
 </P>
 <P>The files src/library.cpp and library.h contain the C-style interface
 to LAMMPS.  See <A HREF = "Section_howto.html#howto_19">Section_howto 19</A> of the