diff --git a/doc/Manual.html b/doc/Manual.html
index 4a0fb04b9b..1d118439ed 100644
--- a/doc/Manual.html
+++ b/doc/Manual.html
@@ -157,6 +157,8 @@ listed above.
   4.17 <A HREF = "Section_howto.html#4_17">Walls</A> 
 <BR>
   4.18 <A HREF = "Section_howto.html#4_18">Elastic constants</A> 
+<BR>
+  4.19 <A HREF = "Section_howto.html#4_19">Library interface to LAMMPS</A> 
 <BR></UL>
 <LI><A HREF = "Section_example.html">Example problems</A> 
 
@@ -166,19 +168,35 @@ listed above.
 
 <LI><A HREF = "Section_modify.html">Modifying & Extending LAMMPS</A> 
 
+<LI><A HREF = "Section_python.html">Python interface</A> 
+
+<UL>  9.1 <A HREF = "Section_python.html#9_1">Extending Python with a serial version of LAMMPS</A> 
+<BR>
+  9.2 <A HREF = "Section_python.html#9_2">Creating a shared MPI library</A> 
+<BR>
+  9.3 <A HREF = "Section_python.html#9_3">Extending Python with a parallel version of LAMMPS</A> 
+<BR>
+  9.4 <A HREF = "Section_python.html#9_4">Extending Python with MPI</A> 
+<BR>
+  9.5 <A HREF = "Section_python.html#9_5">Testing the Python-LAMMPS interface</A> 
+<BR>
+  9.6 <A HREF = "Section_python.html#9_6">Using LAMMPS from Python</A> 
+<BR>
+  9.7 <A HREF = "Section_python.html#9_7">Example Python scripts that use LAMMPS</A> 
+<BR></UL>
 <LI><A HREF = "Section_errors.html">Errors</A> 
 
-<UL>  9.1 <A HREF = "Section_errors.html#9_1">Common problems</A> 
+<UL>  10.1 <A HREF = "Section_errors.html#10_1">Common problems</A> 
 <BR>
-  9.2 <A HREF = "Section_errors.html#9_2">Reporting bugs</A> 
+  10.2 <A HREF = "Section_errors.html#10_2">Reporting bugs</A> 
 <BR>
-  9.3 <A HREF = "Section_errors.html#9_3">Error & warning messages</A> 
+  10.3 <A HREF = "Section_errors.html#10_3">Error & warning messages</A> 
 <BR></UL>
 <LI><A HREF = "Section_history.html">Future and history</A> 
 
-<UL>  10.1 <A HREF = "Section_history.html#10_1">Coming attractions</A> 
+<UL>  11.1 <A HREF = "Section_history.html#11_1">Coming attractions</A> 
 <BR>
-  10.2 <A HREF = "Section_history.html#10_2">Past versions</A> 
+  11.2 <A HREF = "Section_history.html#11_2">Past versions</A> 
 <BR></UL>
 
 </OL>
@@ -249,6 +267,22 @@ listed above.
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
diff --git a/doc/Manual.txt b/doc/Manual.txt
index fb45ce6cfa..f086010e9a 100644
--- a/doc/Manual.txt
+++ b/doc/Manual.txt
@@ -112,18 +112,27 @@ listed above.
   4.15 "Output from LAMMPS (thermo, dumps, computes, fixes, variables)"_4_15 :b
   4.16 "Thermostatting, barostatting, and compute temperature"_4_16 :b
   4.17 "Walls"_4_17 :b
-  4.18 "Elastic constants"_4_18 :ule,b
+  4.18 "Elastic constants"_4_18 :b
+  4.19 "Library interface to LAMMPS"_4_19 :ule,b
 "Example problems"_Section_example.html :l
 "Performance & scalability"_Section_perf.html :l
 "Additional tools"_Section_tools.html :l
 "Modifying & Extending LAMMPS"_Section_modify.html :l
+"Python interface"_Section_python.html :l
+  9.1 "Extending Python with a serial version of LAMMPS"_9_1 :ulb,b
+  9.2 "Creating a shared MPI library"_9_2 :b
+  9.3 "Extending Python with a parallel version of LAMMPS"_9_3 :b
+  9.4 "Extending Python with MPI"_9_4 :b
+  9.5 "Testing the Python-LAMMPS interface"_9_5 :b
+  9.6 "Using LAMMPS from Python"_9_6 :b
+  9.7 "Example Python scripts that use LAMMPS"_9_7 :ule,b
 "Errors"_Section_errors.html :l
-  9.1 "Common problems"_9_1 :ulb,b
-  9.2 "Reporting bugs"_9_2 :b
-  9.3 "Error & warning messages"_9_3 :ule,b
+  10.1 "Common problems"_10_1 :ulb,b
+  10.2 "Reporting bugs"_10_2 :b
+  10.3 "Error & warning messages"_10_3 :ule,b
 "Future and history"_Section_history.html :l
-  10.1 "Coming attractions"_10_1 :ulb,b
-  10.2 "Past versions"_10_2 :ule,b
+  11.1 "Coming attractions"_11_1 :ulb,b
+  11.2 "Past versions"_11_2 :ule,b
 :ole
 
 :link(1_1,Section_intro.html#1_1)
@@ -166,12 +175,21 @@ listed above.
 :link(4_16,Section_howto.html#4_16)
 :link(4_17,Section_howto.html#4_17)
 :link(4_18,Section_howto.html#4_18)
+:link(4_19,Section_howto.html#4_19)
 
-:link(9_1,Section_errors.html#9_1)
-:link(9_2,Section_errors.html#9_2)
-:link(9_3,Section_errors.html#9_3)
+:link(9_1,Section_python.html#9_1)
+:link(9_2,Section_python.html#9_2)
+:link(9_3,Section_python.html#9_3)
+:link(9_4,Section_python.html#9_4)
+:link(9_5,Section_python.html#9_5)
+:link(9_6,Section_python.html#9_6)
+:link(9_7,Section_python.html#9_7)
 
-:link(10_1,Section_history.html#10_1)
-:link(10_2,Section_history.html#10_2)
+:link(10_1,Section_errors.html#10_1)
+:link(10_2,Section_errors.html#10_2)
+:link(10_3,Section_errors.html#10_3)
+
+:link(11_1,Section_history.html#11_1)
+:link(11_2,Section_history.html#11_2)
 
 </BODY>
diff --git a/doc/Section_errors.html b/doc/Section_errors.html
index 22eff1ad29..ebf3222a71 100644
--- a/doc/Section_errors.html
+++ b/doc/Section_errors.html
@@ -1,5 +1,5 @@
 <HTML>
-<CENTER><A HREF = "Section_modify.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> -
+<CENTER><A HREF = "Section_python.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> -
 <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_history.html">Next
 Section</A> 
 </CENTER>
@@ -11,18 +11,18 @@ Section</A>
 
 <HR>
 
-<H3>9. Errors 
+<H3>10. Errors 
 </H3>
 <P>This section describes the various kinds of errors you can encounter
 when using LAMMPS.
 </P>
-9.1 <A HREF = "#9_1">Common problems</A><BR>
-9.2 <A HREF = "#9_2">Reporting bugs</A><BR>
-9.3 <A HREF = "#9_3">Error & warning messages</A> <BR>
+10.1 <A HREF = "#10_1">Common problems</A><BR>
+10.2 <A HREF = "#10_2">Reporting bugs</A><BR>
+10.3 <A HREF = "#10_3">Error & warning messages</A> <BR>
 
 <HR>
 
-<A NAME = "9_1"></A><H4>9.1 Common problems 
+<A NAME = "10_1"></A><H4>10.1 Common problems 
 </H4>
 <P>If two LAMMPS runs do not produce the same answer on different
 machines or different numbers of processors, this is typically not a
@@ -81,7 +81,7 @@ decide if the WARNING is important or not.  A WARNING message that is
 generated in the middle of a run is only printed to the screen, not to
 the logfile, to avoid cluttering up thermodynamic output.  If LAMMPS
 crashes or hangs without spitting out an error message first then it
-could be a bug (see <A HREF = "#9_2">this section</A>) or one of the following
+could be a bug (see <A HREF = "#10_2">this section</A>) or one of the following
 cases:
 </P>
 <P>LAMMPS runs in the available memory a processor allows to be
@@ -112,7 +112,7 @@ buffering or boost the sizes of messages that can be buffered.
 </P>
 <HR>
 
-<A NAME = "9_2"></A><H4>9.2 Reporting bugs 
+<A NAME = "10_2"></A><H4>10.2 Reporting bugs 
 </H4>
 <P>If you are confident that you have found a bug in LAMMPS, follow these
 steps.
@@ -142,7 +142,7 @@ causing the problem.
 </P>
 <HR>
 
-<H4><A NAME = "9_3"></A>9.3 Error & warning messages 
+<H4><A NAME = "10_3"></A>10.3 Error & warning messages 
 </H4>
 <P>These are two alphabetic lists of the <A HREF = "#error">ERROR</A> and
 <A HREF = "#warn">WARNING</A> messages LAMMPS prints out and the reason why.  If the
diff --git a/doc/Section_errors.txt b/doc/Section_errors.txt
index 9bfdffc9df..8706782413 100644
--- a/doc/Section_errors.txt
+++ b/doc/Section_errors.txt
@@ -1,4 +1,4 @@
-"Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws -
+"Previous Section"_Section_python.html - "LAMMPS WWW Site"_lws -
 "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
 Section"_Section_history.html :c
 
@@ -8,18 +8,18 @@ Section"_Section_history.html :c
 
 :line
 
-9. Errors :h3
+10. Errors :h3
 
 This section describes the various kinds of errors you can encounter
 when using LAMMPS.
 
-9.1 "Common problems"_#9_1
-9.2 "Reporting bugs"_#9_2
-9.3 "Error & warning messages"_#9_3 :all(b)
+10.1 "Common problems"_#10_1
+10.2 "Reporting bugs"_#10_2
+10.3 "Error & warning messages"_#10_3 :all(b)
 
 :line
 
-9.1 Common problems :link(9_1),h4
+10.1 Common problems :link(10_1),h4
 
 If two LAMMPS runs do not produce the same answer on different
 machines or different numbers of processors, this is typically not a
@@ -78,7 +78,7 @@ decide if the WARNING is important or not.  A WARNING message that is
 generated in the middle of a run is only printed to the screen, not to
 the logfile, to avoid cluttering up thermodynamic output.  If LAMMPS
 crashes or hangs without spitting out an error message first then it
-could be a bug (see "this section"_#9_2) or one of the following
+could be a bug (see "this section"_#10_2) or one of the following
 cases:
 
 LAMMPS runs in the available memory a processor allows to be
@@ -109,7 +109,7 @@ buffering or boost the sizes of messages that can be buffered.
 
 :line
 
-9.2 Reporting bugs :link(9_2),h4
+10.2 Reporting bugs :link(10_2),h4
 
 If you are confident that you have found a bug in LAMMPS, follow these
 steps.
@@ -139,7 +139,7 @@ As a last resort, you can send an email directly to the
 
 :line
 
-9.3 Error & warning messages :h4,link(9_3)
+10.3 Error & warning messages :h4,link(10_3)
 
 These are two alphabetic lists of the "ERROR"_#error and
 "WARNING"_#warn messages LAMMPS prints out and the reason why.  If the
diff --git a/doc/Section_history.html b/doc/Section_history.html
index 8fe4156330..8a414e4a47 100644
--- a/doc/Section_history.html
+++ b/doc/Section_history.html
@@ -9,18 +9,18 @@
 
 <HR>
 
-<H3>10. Future and history 
+<H3>11. Future and history 
 </H3>
 <P>This section lists features we are planning to add to LAMMPS, features
 of previous versions of LAMMPS, and features of other parallel
 molecular dynamics codes I've distributed.
 </P>
-10.1 <A HREF = "#10_1">Coming attractions</A><BR>
-10.2 <A HREF = "#10_2">Past versions</A> <BR>
+11.1 <A HREF = "#11_1">Coming attractions</A><BR>
+11.2 <A HREF = "#11_2">Past versions</A> <BR>
 
 <HR>
 
-<H4><A NAME = "10_1"></A>10.1 Coming attractions 
+<H4><A NAME = "11_1"></A>11.1 Coming attractions 
 </H4>
 <P>The current version of LAMMPS incorporates nearly all the features
 from previous parallel MD codes developed at Sandia.  These include
@@ -49,7 +49,7 @@ page</A> on the LAMMPS WWW site for more details.
 </UL>
 <HR>
 
-<H4><A NAME = "10_2"></A>10.2 Past versions 
+<H4><A NAME = "11_2"></A>11.2 Past versions 
 </H4>
 <P>LAMMPS development began in the mid 1990s under a cooperative research
 & development agreement (CRADA) between two DOE labs (Sandia and LLNL)
diff --git a/doc/Section_history.txt b/doc/Section_history.txt
index 6e17ca611d..93922ebd45 100644
--- a/doc/Section_history.txt
+++ b/doc/Section_history.txt
@@ -6,18 +6,18 @@
 
 :line
 
-10. Future and history :h3
+11. Future and history :h3
 
 This section lists features we are planning to add to LAMMPS, features
 of previous versions of LAMMPS, and features of other parallel
 molecular dynamics codes I've distributed.
 
-10.1 "Coming attractions"_#10_1
-10.2 "Past versions"_#10_2 :all(b)
+11.1 "Coming attractions"_#11_1
+11.2 "Past versions"_#11_2 :all(b)
 
 :line
 
-10.1 Coming attractions :h4,link(10_1)
+11.1 Coming attractions :h4,link(11_1)
 
 The current version of LAMMPS incorporates nearly all the features
 from previous parallel MD codes developed at Sandia.  These include
@@ -46,7 +46,7 @@ Direct Simulation Monte Carlo - DSMC :ul
 
 :line
 
-10.2 Past versions :h4,link(10_2)
+11.2 Past versions :h4,link(11_2)
 
 LAMMPS development began in the mid 1990s under a cooperative research
 & development agreement (CRADA) between two DOE labs (Sandia and LLNL)
diff --git a/doc/Section_howto.html b/doc/Section_howto.html
index 48bd325ecd..8fefdedfbe 100644
--- a/doc/Section_howto.html
+++ b/doc/Section_howto.html
@@ -11,8 +11,8 @@
 
 <H3>4. How-to discussions 
 </H3>
-<P>The following sections describe what commands can be used to perform
-certain kinds of LAMMPS simulations.
+<P>The following sections describe how to use various options within
+LAMMPS.
 </P>
 4.1 <A HREF = "#4_1">Restarting a simulation</A><BR>
 4.2 <A HREF = "#4_2">2d simulations</A><BR>
@@ -31,11 +31,12 @@ certain kinds of LAMMPS simulations.
 4.15 <A HREF = "#4_15">Output from LAMMPS (thermo, dumps, computes, fixes, variables)</A><BR>
 4.16 <A HREF = "#4_16">Thermostatting, barostatting and computing temperature</A><BR>
 4.17 <A HREF = "#4_17">Walls</A><BR>
-4.18 <A HREF = "#4_18">Elastic constants</A> <BR>
+4.18 <A HREF = "#4_18">Elastic constants</A><BR>
+4.19 <A HREF = "#4_19">Library interface to LAMMPS</A> <BR>
 
 <P>The example input scripts included in the LAMMPS distribution and
 highlighted in <A HREF = "Section_example.html">this section</A> also show how to
-setup and run various kinds of problems.
+setup and run various kinds of simulations.
 </P>
 <HR>
 
@@ -654,53 +655,31 @@ strain induced across grain boundaries
 
 <P><A HREF = "Section_start.html#2_4">This section</A> of the documentation describes
 how to build LAMMPS as a library.  Once this is done, you can
-interface with LAMMPS either via C++, C, or Fortran (or any other
-language that supports a vanilla C-like interface, e.g. a scripting
-language).  For example, from C++ you could create one (or more)
-"instances" of LAMMPS, pass it an input script to process, or execute
-individual commands, all by invoking the correct class methods in
-LAMMPS.  From C or Fortran you can make function calls to do the same
-things.  Library.cpp and library.h contain such a C interface with the
-functions:
+interface with LAMMPS either via C++, C, Fortran, or Python (or any
+other language that supports a vanilla C-like interface).  For
+example, from C++ you could create one (or more) "instances" of
+LAMMPS, pass it an input script to process, or execute individual
+commands, all by invoking the correct class methods in LAMMPS.  From C
+or Fortran you can make function calls to do the same things.  See
+<A HREF = "Section_python.html">this section</A> of the manual for a description of
+the Python wrapper provided with LAMMPS that operates through the
+LAMMPS library interface.
 </P>
-<PRE>void lammps_open(int, char **, MPI_Comm, void **);
-void lammps_close(void *);
-void lammps_file(void *, char *);
-char *lammps_command(void *, char *); 
-</PRE>
-<P>The functions contain C++ code you could write in a C++ application
-that was invoking LAMMPS directly.  Note that LAMMPS classes are
-defined within a LAMMPS namespace (LAMMPS_NS) if you use them
-from another C++ application.
+<P>The files src/library.cpp and library.h contain the C-style interface
+to LAMMPS.  See <A HREF = "Section_howto.html#4_19">this section</A> of the manual
+for a description of the interface and how to extend it for your
+needs.
 </P>
-<P>Two of the routines in library.cpp are of particular note.  The
-lammps_open() function initiates LAMMPS and takes an MPI communicator
-as an argument.  It returns a pointer to a LAMMPS "object".  As with
-C++, the lammps_open() function can be called multiple times, to
-create multiple instances of LAMMPS.
-</P>
-<P>LAMMPS will run on the set of processors in the communicator.  This
-means the calling code can run LAMMPS on all or a subset of
-processors.  For example, a wrapper script might decide to alternate
-between LAMMPS and another code, allowing them both to run on all the
-processors.  Or it might allocate half the processors to LAMMPS and
-half to the other code and run both codes simultaneously before
-syncing them up periodically.
-</P>
-<P>Library.cpp contains a lammps_command() function to which the caller
-passes a single LAMMPS command (a string).  Thus the calling code can
-read or generate a series of LAMMPS commands (e.g. an input script)
-one line at a time and pass it thru the library interface to setup a
-problem and then run it.
-</P>
-<P>A few other sample functions are included in library.cpp, but the key
-idea is that you can write any functions you wish to define an
-interface for how your code talks to LAMMPS and add them to
-library.cpp and library.h.  The routines you add can access any LAMMPS
-data.  The examples/couple directory has example C++ and C codes which
-show how a stand-alone code can link LAMMPS as a library, run LAMMPS
-on a subset of processors, grab data from LAMMPS, change it, and put
-it back into LAMMPS.
+<P>Note that the lammps_open() function that creates an instance of
+LAMMPS takes an MPI communicator as an argument.  This means that
+instance of LAMMPS will run on the set of processors in the
+communicator.  Thus the calling code can run LAMMPS on all or a subset
+of processors.  For example, a wrapper script might decide to
+alternate between LAMMPS and another code, allowing them both to run
+on all the processors.  Or it might allocate half the processors to
+LAMMPS and half to the other code and run both codes simultaneously
+before syncing them up periodically.  Or it might instantiate multiple
+instances of LAMMPS to perform different calculations.
 </P>
 <HR>
 
@@ -1648,6 +1627,86 @@ converge and requires careful post-processing <A HREF = "#Shinoda">(Shinoda)</A>
 </P>
 <HR>
 
+<A NAME = "4_19"></A><H4>4.19 Library interface to LAMMPS 
+</H4>
+<P>As described in <A HREF = "Section_start.html#2_4">this section</A>, LAMMPS can be
+built as a library, so that it can be called by another code, used in
+a <A HREF = "Section_howto.html#4_10">coupled manner</A> with other codes, or driven
+through a <A HREF = "Section_python.html">Python interface</A>.
+</P>
+<P>All of these methodologies use a C-style interface to LAMMPS that is
+provided in the files src/library.cpp and src/library.h.  The
+functions therein have a C-style argument list, but contain C++ code
+you could write yourself in a C++ application that was invoking LAMMPS
+directly.  The C++ code in the functions illustrates how to invoke
+internal LAMMPS operations.  Note that LAMMPS classes are defined
+within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++
+application.
+</P>
+<P>Library.cpp contains these 4 functions:
+</P>
+<PRE>void lammps_open(int, char **, MPI_Comm, void **);
+void lammps_close(void *);
+void lammps_file(void *, char *);
+char *lammps_command(void *, char *); 
+</PRE>
+<P>The lammps_open() function is used to initialize LAMMPS, passing in a
+list of strings as if they were <A HREF = "#2_6">command-line arguments</A> when
+LAMMPS is run in stand-alone mode from the command line, and a MPI
+communicator for LAMMPS to run under.  It returns a ptr to the LAMMPS
+object that is created, and which is used in subsequent library calls.
+The lammps_open() function can be called multiple times, to create
+multiple instances of LAMMPS.
+</P>
+<P>LAMMPS will run on the set of processors in the communicator.  This
+means the calling code can run LAMMPS on all or a subset of
+processors.  For example, a wrapper script might decide to alternate
+between LAMMPS and another code, allowing them both to run on all the
+processors.  Or it might allocate half the processors to LAMMPS and
+half to the other code and run both codes simultaneously before
+syncing them up periodically.  Or it might instantiate multiple
+instances of LAMMPS to perform different calculations.
+</P>
+<P>The lammps_close() function is used to shut down an instance of LAMMPS
+and free all its memory.
+</P>
+<P>The lammps_file() and lammps_command() functions are used to pass a
+file or string to LAMMPS as if it were an input script or single
+command in an input script.  Thus the calling code can read or
+generate a series of LAMMPS commands one line at a time and pass it
+thru the library interface to setup a problem and then run it,
+interleaving the lammps_command() calls with other calls to extract
+information from LAMMPS, perform its own operations, or call another
+code's library.
+</P>
+<P>Other useful functions are also included in library.cpp.  For example:
+</P>
+<PRE>void *lammps_extract_global(void *, char *)
+void *lammps_extract_atom(void *, char *)
+void *lammps_extract_compute(void *, char *, int, int)
+void *lammps_extract_fix(void *, char *, int, int, int, int)
+void *lammps_extract_variable(void *, char *, char *)
+int lammps_get_natoms(void *)
+void lammps_get_coords(void *, double *)
+void lammps_put_coords(void *, double *) 
+</PRE>
+<P>These can extract various global or per-atom quantities from LAMMPS as
+well as values calculated by a compute, fix, or variable.  The "get"
+and "put" operations can retrieve and reset atom coordinates.
+See the library.cpp file and its associated header file library.h for
+details.
+</P>
+<P>The key idea of the library interface is that you can write any
+functions you wish to define how your code talks to LAMMPS and add
+them to src/library.cpp and src/library.h, as well as to the <A HREF = "doc/Section_python.html">Python
+interface</A>.  The routines you add can access
+or change any LAMMPS data you wish.  The couple and python directories
+have example C++ and C and Python codes which show how a driver code
+can link to LAMMPS as a library, run LAMMPS on a subset of processors,
+grab data from LAMMPS, change it, and put it back into LAMMPS.
+</P>
+<HR>
+
 <HR>
 
 <A NAME = "Berendsen"></A>
diff --git a/doc/Section_howto.txt b/doc/Section_howto.txt
index d83ed84d59..d6d2e6592c 100644
--- a/doc/Section_howto.txt
+++ b/doc/Section_howto.txt
@@ -8,8 +8,8 @@
 
 4. How-to discussions :h3
 
-The following sections describe what commands can be used to perform
-certain kinds of LAMMPS simulations.
+The following sections describe how to use various options within
+LAMMPS.
 
 4.1 "Restarting a simulation"_#4_1
 4.2 "2d simulations"_#4_2
@@ -28,11 +28,12 @@ certain kinds of LAMMPS simulations.
 4.15 "Output from LAMMPS (thermo, dumps, computes, fixes, variables)"_#4_15
 4.16 "Thermostatting, barostatting and computing temperature"_#4_16
 4.17 "Walls"_#4_17
-4.18 "Elastic constants"_#4_18 :all(b)
+4.18 "Elastic constants"_#4_18
+4.19 "Library interface to LAMMPS"_#4_19 :all(b)
 
 The example input scripts included in the LAMMPS distribution and
 highlighted in "this section"_Section_example.html also show how to
-setup and run various kinds of problems.
+setup and run various kinds of simulations.
 
 :line
 
@@ -649,53 +650,31 @@ strain induced across grain boundaries :l,ule
 
 "This section"_Section_start.html#2_4 of the documentation describes
 how to build LAMMPS as a library.  Once this is done, you can
-interface with LAMMPS either via C++, C, or Fortran (or any other
-language that supports a vanilla C-like interface, e.g. a scripting
-language).  For example, from C++ you could create one (or more)
-"instances" of LAMMPS, pass it an input script to process, or execute
-individual commands, all by invoking the correct class methods in
-LAMMPS.  From C or Fortran you can make function calls to do the same
-things.  Library.cpp and library.h contain such a C interface with the
-functions:
+interface with LAMMPS either via C++, C, Fortran, or Python (or any
+other language that supports a vanilla C-like interface).  For
+example, from C++ you could create one (or more) "instances" of
+LAMMPS, pass it an input script to process, or execute individual
+commands, all by invoking the correct class methods in LAMMPS.  From C
+or Fortran you can make function calls to do the same things.  See
+"this section"_Section_python.html of the manual for a description of
+the Python wrapper provided with LAMMPS that operates through the
+LAMMPS library interface.
 
-void lammps_open(int, char **, MPI_Comm, void **);
-void lammps_close(void *);
-void lammps_file(void *, char *);
-char *lammps_command(void *, char *); :pre
+The files src/library.cpp and library.h contain the C-style interface
+to LAMMPS.  See "this section"_Section_howto.html#4_19 of the manual
+for a description of the interface and how to extend it for your
+needs.
 
-The functions contain C++ code you could write in a C++ application
-that was invoking LAMMPS directly.  Note that LAMMPS classes are
-defined within a LAMMPS namespace (LAMMPS_NS) if you use them
-from another C++ application.
-
-Two of the routines in library.cpp are of particular note.  The
-lammps_open() function initiates LAMMPS and takes an MPI communicator
-as an argument.  It returns a pointer to a LAMMPS "object".  As with
-C++, the lammps_open() function can be called multiple times, to
-create multiple instances of LAMMPS.
-
-LAMMPS will run on the set of processors in the communicator.  This
-means the calling code can run LAMMPS on all or a subset of
-processors.  For example, a wrapper script might decide to alternate
-between LAMMPS and another code, allowing them both to run on all the
-processors.  Or it might allocate half the processors to LAMMPS and
-half to the other code and run both codes simultaneously before
-syncing them up periodically.
-
-Library.cpp contains a lammps_command() function to which the caller
-passes a single LAMMPS command (a string).  Thus the calling code can
-read or generate a series of LAMMPS commands (e.g. an input script)
-one line at a time and pass it thru the library interface to setup a
-problem and then run it.
-
-A few other sample functions are included in library.cpp, but the key
-idea is that you can write any functions you wish to define an
-interface for how your code talks to LAMMPS and add them to
-library.cpp and library.h.  The routines you add can access any LAMMPS
-data.  The examples/couple directory has example C++ and C codes which
-show how a stand-alone code can link LAMMPS as a library, run LAMMPS
-on a subset of processors, grab data from LAMMPS, change it, and put
-it back into LAMMPS.
+Note that the lammps_open() function that creates an instance of
+LAMMPS takes an MPI communicator as an argument.  This means that
+instance of LAMMPS will run on the set of processors in the
+communicator.  Thus the calling code can run LAMMPS on all or a subset
+of processors.  For example, a wrapper script might decide to
+alternate between LAMMPS and another code, allowing them both to run
+on all the processors.  Or it might allocate half the processors to
+LAMMPS and half to the other code and run both codes simultaneously
+before syncing them up periodically.  Or it might instantiate multiple
+instances of LAMMPS to perform different calculations.
 
 :line 
 
@@ -1634,6 +1613,86 @@ tensor. Another approach is to sample the triclinic cell fluctuations
 that occur in an NPT simulation. This method can also be slow to
 converge and requires careful post-processing "(Shinoda)"_#Shinoda
 
+:line
+
+4.19 Library interface to LAMMPS :link(4_19),h4
+
+As described in "this section"_Section_start.html#2_4, LAMMPS can be
+built as a library, so that it can be called by another code, used in
+a "coupled manner"_Section_howto.html#4_10 with other codes, or driven
+through a "Python interface"_Section_python.html.
+
+All of these methodologies use a C-style interface to LAMMPS that is
+provided in the files src/library.cpp and src/library.h.  The
+functions therein have a C-style argument list, but contain C++ code
+you could write yourself in a C++ application that was invoking LAMMPS
+directly.  The C++ code in the functions illustrates how to invoke
+internal LAMMPS operations.  Note that LAMMPS classes are defined
+within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++
+application.
+
+Library.cpp contains these 4 functions:
+
+void lammps_open(int, char **, MPI_Comm, void **);
+void lammps_close(void *);
+void lammps_file(void *, char *);
+char *lammps_command(void *, char *); :pre
+
+The lammps_open() function is used to initialize LAMMPS, passing in a
+list of strings as if they were "command-line arguments"_#2_6 when
+LAMMPS is run in stand-alone mode from the command line, and a MPI
+communicator for LAMMPS to run under.  It returns a ptr to the LAMMPS
+object that is created, and which is used in subsequent library calls.
+The lammps_open() function can be called multiple times, to create
+multiple instances of LAMMPS.
+
+LAMMPS will run on the set of processors in the communicator.  This
+means the calling code can run LAMMPS on all or a subset of
+processors.  For example, a wrapper script might decide to alternate
+between LAMMPS and another code, allowing them both to run on all the
+processors.  Or it might allocate half the processors to LAMMPS and
+half to the other code and run both codes simultaneously before
+syncing them up periodically.  Or it might instantiate multiple
+instances of LAMMPS to perform different calculations.
+
+The lammps_close() function is used to shut down an instance of LAMMPS
+and free all its memory.
+
+The lammps_file() and lammps_command() functions are used to pass a
+file or string to LAMMPS as if it were an input script or single
+command in an input script.  Thus the calling code can read or
+generate a series of LAMMPS commands one line at a time and pass it
+thru the library interface to setup a problem and then run it,
+interleaving the lammps_command() calls with other calls to extract
+information from LAMMPS, perform its own operations, or call another
+code's library.
+
+Other useful functions are also included in library.cpp.  For example:
+
+void *lammps_extract_global(void *, char *)
+void *lammps_extract_atom(void *, char *)
+void *lammps_extract_compute(void *, char *, int, int)
+void *lammps_extract_fix(void *, char *, int, int, int, int)
+void *lammps_extract_variable(void *, char *, char *)
+int lammps_get_natoms(void *)
+void lammps_get_coords(void *, double *)
+void lammps_put_coords(void *, double *) :pre
+
+These can extract various global or per-atom quantities from LAMMPS as
+well as values calculated by a compute, fix, or variable.  The "get"
+and "put" operations can retrieve and reset atom coordinates.
+See the library.cpp file and its associated header file library.h for
+details.
+
+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 "Python
+interface"_doc/Section_python.html.  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.
+
 :line
 :line
 
diff --git a/doc/Section_intro.html b/doc/Section_intro.html
index 658010c981..7c8220fbbb 100644
--- a/doc/Section_intro.html
+++ b/doc/Section_intro.html
@@ -413,7 +413,7 @@ Site</A>, or have a suggestion for something to clarify or include,
 send an email to the
 <A HREF = "http://lammps.sandia.gov/authors.html">developers</A>. 
 
-<LI>If you find a bug, <A HREF = "Section_errors.html#9_2">this section</A> describes
+<LI>If you find a bug, <A HREF = "Section_errors.html#10_2">this section</A> describes
 how to report it. 
 
 <LI>If you publish a paper using LAMMPS results, send the citation (and
diff --git a/doc/Section_intro.txt b/doc/Section_intro.txt
index c2021d7650..9f545e8108 100644
--- a/doc/Section_intro.txt
+++ b/doc/Section_intro.txt
@@ -403,7 +403,7 @@ Site"_lws, or have a suggestion for something to clarify or include,
 send an email to the
 "developers"_http://lammps.sandia.gov/authors.html. :l
 
-If you find a bug, "this section"_Section_errors.html#9_2 describes
+If you find a bug, "this section"_Section_errors.html#10_2 describes
 how to report it. :l
 
 If you publish a paper using LAMMPS results, send the citation (and
diff --git a/doc/Section_modify.html b/doc/Section_modify.html
index 8779445df9..5b05b3e50f 100644
--- a/doc/Section_modify.html
+++ b/doc/Section_modify.html
@@ -1,6 +1,6 @@
 <HTML>
 <CENTER><A HREF = "Section_tools.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> -
-<A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_errors.html">Next
+<A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_python.html">Next
 Section</A> 
 </CENTER>
 
diff --git a/doc/Section_modify.txt b/doc/Section_modify.txt
index 93e38333df..5309b38c81 100644
--- a/doc/Section_modify.txt
+++ b/doc/Section_modify.txt
@@ -1,6 +1,6 @@
 "Previous Section"_Section_tools.html - "LAMMPS WWW Site"_lws -
 "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
-Section"_Section_errors.html :c
+Section"_Section_python.html :c
 
 :link(lws,http://lammps.sandia.gov)
 :link(ld,Manual.html)
diff --git a/doc/Section_python.html b/doc/Section_python.html
new file mode 100644
index 0000000000..7b98a0cb8d
--- /dev/null
+++ b/doc/Section_python.html
@@ -0,0 +1,620 @@
+<HTML>
+<CENTER><A HREF = "Section_modify.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_errors.html">Next Section</A> 
+</CENTER>
+
+
+
+
+
+
+<HR>
+
+<H3>9. Python interface to LAMMPS 
+</H3>
+<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>
+<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
+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#4_10">this
+section</A> of the manual and the couple
+directory of the distribution for more ideas about coupling LAMMPS to
+other codes.  See <A HREF = "Section_start.html#2_4">this section</A> about how to
+build LAMMPS as a library, and <A HREF = "Section_howto.html#4_19">this 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.
+</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>
+<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>
+<P>Thus you should first decide how you intend to use LAMMPS from Python.
+There are 3 options:
+</P>
+<P>(1) Use LAMMPS on a single processor running Python.
+</P>
+<P>(2) Use LAMMPS in parallel, where each processor runs Python, but your
+Python program does not use MPI.
+</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>
+<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.
+</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>
+<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.
+</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>
+<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>
+<UL><LI><A HREF = "#9_1">Extending Python with a serial version of LAMMPS</A>
+<LI><A HREF = "#9_2">Creating a shared MPI library</A>
+<LI><A HREF = "#9_3">Extending Python with a parallel version of LAMMPS</A>
+<LI><A HREF = "#9_4">Extending Python with MPI</A>
+<LI><A HREF = "#9_5">Testing the Python-LAMMPS interface</A>
+<LI><A HREF = "#9_6">Using LAMMPS from Python</A>
+<LI><A HREF = "#9_7">Example Python scripts that use LAMMPS</A> 
+</UL>
+<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
+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#2_3">this
+section</A> of the manual for a discussion of
+LAMMPS pacakges.  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>
+<HR>
+
+<HR>
+
+<A NAME = "9_1"></A><H4>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".
+</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_serial.so</I> file will be put in the appropriate directory.
+</P>
+<HR>
+
+<A NAME = "9_2"></A><H4>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-sharedlib=gcc
+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
+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 will typically fail if the linker uses libmpich.so
+instead.  This 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 = "9_3"></A><H4>Extending Python with a parallel version of LAMMPS 
+</H4>
+<P>From the python directory, type
+</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 = "9_4"></A><H4>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>
+<P>These include
+</P>
+<UL><LI><A HREF = "http://pympi.sourceforge.net/">pyMPI</A>
+<LI><A HREF = "http://code.google.com/p/maroonmpi/">maroonmpi</A>
+<LI><A HREF = "http://code.google.com/p/mpi4py/">mpi4py</A>
+<LI><A HREF = "http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16">myMPI</A>
+<LI><A HREF = "http://datamining.anu.edu.au/~ole/pypar">Pypar</A> 
+</UL>
+<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),
+and exposing (some portion of) its interface to your Python script.
+This means they 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
+itself) as a result.
+</P>
+<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
+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.
+</P>
+<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
+package</A> be installed in your Python.  After
+launching python, type
+</P>
+<PRE>>>> import numpy 
+</PRE>
+<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
+top-level directory, type
+</P>
+<PRE>python setup.py build
+sudo python setup.py install 
+</PRE>
+<P>The "sudo" is only needed if required to copy Numpy files into your
+Python distribution's site-packages directory.
+</P>
+<P>To install Pypar (version pypar-2.1.0_66 as of April 2009), unpack it
+and from its "source" directory, type
+</P>
+<PRE>python setup.py build
+sudo python setup.py install 
+</PRE>
+<P>Again, the "sudo" is only needed if required to copy PyPar files into
+your Python distribution's site-packages directory.
+</P>
+<P>If you have successully installed Pypar, you should be able to run
+python serially and type
+</P>
+<PRE>>>> import pypar 
+</PRE>
+<P>without error.  You should also be able to run python in parallel
+on a simple test script
+</P>
+<PRE>% mpirun -np 4 python test.script 
+</PRE>
+<P>where test.script contains the lines
+</P>
+<PRE>import pypar
+print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) 
+</PRE>
+<P>and see one line of output for each processor you ran on.
+</P>
+<HR>
+
+<A NAME = "9_5"></A><H4>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>
+<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>
+<PRE>% mpirun -np 4 python test.script 
+</PRE>
+<P>where test.script contains the lines
+</P>
+<PRE>import pypar
+from lammps import lammps
+lmp = lammps()
+print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()), lmp
+pypar.finalize() 
+</PRE>
+<P>Again, if you get no errors, you're good to go.
+</P>
+<P>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.
+</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
+pypar.finalize(), to insure MPI is shut down correctly.
+</P>
+<P>Also note that a Python script can be invoked in one of several ways:
+</P>
+<P>% python foo.script
+% python -i foo.script
+% foo.script
+</P>
+<P>The last command requires that the first line of the script be
+something like this:
+</P>
+<P>#!/usr/local/bin/python 
+#!/usr/local/bin/python -i
+</P>
+<P>where the path points to where you have Python installed, and that you
+have made the script file executable:
+</P>
+<P>% chmod +x foo.script
+</P>
+<P>Without the "-i" flag, Python will exit when the script finishes.
+With the "-i" flag, you will be left in the Python interpreter when
+the script finishes, so you can type subsequent commands.  As
+mentioned above, you can only run Python interactively when running
+Python on a single processor, not in parallel.
+</P>
+<HR>
+
+<HR>
+
+<A NAME = "9_6"></A><H4>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
+"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:
+</P>
+<PRE>from lammps import lammps 
+from lammps import LMPINT as INT
+from lammps import LMPDOUBLE as DOUBLE
+from lammps import LMPIPTR as IPTR
+from lammps import LMPDPTR as DPTR
+from lammps import LMPDPTRPTR as DPTRPTR 
+</PRE>
+<P>These are the methods defined by the lammps module.  If you look
+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.
+</P>
+<PRE>lmp = lammps()           # create a LAMMPS object
+lmp = lammps(list)       # ditto, with command-line args, list = ["-echo","screen"] 
+</PRE>
+<PRE>lmp.close()              # destroy a LAMMPS object 
+</PRE>
+<PRE>lmp.file(file)           # run an entire input script, file = "in.lj"
+lmp.command(cmd)         # invoke a single LAMMPS command, cmd = "run 100" 
+</PRE>
+<PRE>xlo = lmp.extract_global(name,type)  # extract a global quantity
+                                     # name = "boxxlo", "nlocal", etc
+				     # type = INT or DOUBLE 
+</PRE>
+<PRE>coords = lmp.extract_atom(name,type)      # extract a per-atom quantity
+                                          # name = "x", "type", etc
+				          # type = IPTR or DPTR or DPTRPTR 
+</PRE>
+<PRE>eng = 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
+					  # style = 0 = global data
+					  #	    1 = per-atom data
+					  #         2 = local data
+					  # type = 0 = scalar
+					  #	   1 = vector
+					  #        2 = array
+					  # i,j = indices of value in global vector or array 
+</PRE>
+<PRE>var = lmp.extract_variable(name,group,flag)  # extract value(s) from a variable
+	                                     # name = name of variable
+					     # group = group ID (ignored for equal-style variables)
+					     # flag = 0 = equal-style variable
+					     #        1 = atom-style variable 
+</PRE>
+<PRE>natoms = lmp.get_natoms()                 # total # of atoms as int
+x = lmp.get_coords()                      # return coords of all atoms in x
+lmp.put_coords(x)                         # set all atom coords via x 
+</PRE>
+<HR>
+
+<P>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.
+</P>
+<P>The file() and command() methods allow an input script or single
+commands to be invoked.
+</P>
+<P>The extract_global(), extract_atom(), extract_compute(),
+extract_fix(), and extract_variable() methods return values or
+pointers to data structures internal to LAMMPS.
+</P>
+<P>For extract_global() see the src/library.cpp file for the list of
+valid names.  New names could easily be added.  A double or integer is
+returned.  You need to specify the appropriate data type via the type
+argument.
+</P>
+<P>For extract_atom(), a pointer to internal LAMMPS atom-based data is
+returned, which you can use via normal Python subscripting.  See the
+extract() method in the src/atom.cpp file for a list of valid names.
+Again, new names could easily be added.  A pointer to a vector of
+doubles or integers, or a pointer to an array of doubles (double **)
+is returned.  You need to specify the appropriate data type via the
+type argument.
+</P>
+<P>For extract_compute() and extract_fix(), the global, per-atom, or
+local data calulated by the compute or fix can be accessed.  What is
+returned depends on whether the compute or fix calculates a scalar or
+vector or array.  For a scalar, a single double value is returned.  If
+the compute or fix calculates a vector or array, a pointer to the
+internal LAMMPS data is returned, which you can use via normal Python
+subscripting.  The one exception is that for a fix that calculates a
+global vector or array, a single double value from the vector or array
+is returned, indexed by I (vector) or I and J (array).  I,J are
+zero-based indices.  The I,J arguments can be left out if not needed.
+See <A HREF = "Section_howto.html#4_15">this section</A> of the manual for a
+discussion of global, per-atom, and local data, and of scalar, vector,
+and array data types.  See the doc pages for individual
+<A HREF = "compute.html">computes</A> and <A HREF = "fix.html">fixes</A> for a description of what
+they calculate and store.
+</P>
+<P>For extract_variable(), an <A HREF = "variable.html">equal-style or atom-style
+variable</A> is evaluated and its result returned.
+</P>
+<P>For equal-style variables a single double value is returned and the
+group argument is ignored.  For atom-style variables, a vector of
+doubles is returned, one value per atom, which you can use via normal
+Python subscripting. The values will be zero for atoms not in the
+specified group.
+</P>
+<P>The get_natoms() method returns the total number of atoms in the
+simulation, as an int.  Note that extract_global("natoms") returns the
+same value, but as a double, which is the way LAMMPS stores it to
+allow for systems with more atoms than can be stored in an int (> 2
+billion).
+</P>
+<P>The get_coords() method returns an ctypes vector of doubles of length
+3*natoms, for the coordinates of all the atoms in the simulation,
+ordered by x,y,z and then by atom ID (see code for put_coords()
+below).  The array can be used via normal Python subscripting.  If
+atom IDs are not consecutively ordered within LAMMPS, a None is
+returned as indication of an error.
+</P>
+<P>Note that the data structure get_coords() returns is different from
+the data structure returned by extract_atom("x") in four ways.  (1)
+Get_coords() returns a vector which you index as x[i];
+extract_atom() returns an array which you index as x[i][j].  (2)
+Get_coords() orders the atoms by atom ID while extract_atom() does
+not.  (3) Get_coords() returns a list of all atoms in the simulation;
+extract_atoms() returns just the atoms local to each processor.  (4)
+Finally, the get_coords() data structure is a copy of the atom coords
+stored internally in LAMMPS, whereas extract_atom returns an array
+that points directly to the internal data.  This means you can change
+values inside LAMMPS from Python by assigning a new values to the
+extract_atom() array.  To do this with the get_atoms() vector, you
+need to change values in the vector, then invoke the put_coords()
+method.
+</P>
+<P>The put_coords() method takes a vector of coordinates for all atoms in
+the simulation, assumed to be ordered by x,y,z and then by atom ID,
+and uses the values to overwrite the corresponding coordinates for
+each atom inside LAMMPS.  This requires LAMMPS to have its "map"
+option enabled; see the <A HREF = "atom_modify.html">atom_modify</A> command for
+details.  If it is not or if atom IDs are not consecutively ordered,
+no coordinates are reset,
+</P>
+<P>The array of coordinates passed to put_coords() must be a ctypes
+vector of doubles, allocated and initialized something like this:
+</P>
+<PRE>from ctypes import *
+natoms = lmp.get_atoms()
+n3 = 3*natoms
+x = (c_double*n3)()
+x<B>0</B> = x coord of atom with ID 1
+x<B>1</B> = y coord of atom with ID 1
+x<B>2</B> = z coord of atom with ID 1
+x<B>3</B> = x coord of atom with ID 2
+...
+x<B>n3-1</B> = z coord of atom with ID natoms
+lmp.put_coords(x) 
+</PRE>
+<P>Alternatively, you can just change values in the vector returned by
+get_coords(), since it is a ctypes vector of doubles.
+</P>
+<HR>
+
+<P>As noted above, these Python class methods correspond one-to-one with
+the functions in the LAMMPS library interface in src/library.cpp and
+library.h.  This means you can extend the Python wrapper via the
+following steps:
+</P>
+<UL><LI>Add a new interface function to src/library.cpp and
+src/library.h. 
+
+<LI>Verify the new function is syntactically correct by building LAMMPS as
+a library - see <A HREF = "Section_start.html#2_4">this section</A> of the
+manual. 
+
+<LI>Add a wrapper method in the Python LAMMPS module to python/lammps.py
+for this interface 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
+Python script.  Isn't ctypes amazing? 
+</UL>
+<HR>
+
+<HR>
+
+<A NAME = "9_7"></A><H4>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
+things that are possible when Python wraps LAMMPS.  If you create your
+own scripts, send them to us and we can include them in the LAMMPS
+distribution.
+</P>
+<DIV ALIGN=center><TABLE  BORDER=1 >
+<TR><TD >trivial.py</TD><TD > read/run a LAMMPS input script via Python</TD></TR>
+<TR><TD >demo.py</TD><TD > invoke various LAMMPS library interface routines</TD></TR>
+<TR><TD >simple.py</TD><TD > mimic operation of couple/simple/simple.cpp in Python</TD></TR>
+<TR><TD >gui.py</TD><TD > GUI go/stop/temperature-slider to control LAMMPS</TD></TR>
+<TR><TD >plot.py</TD><TD > real-time temeperature plot with GnuPlot via <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A></TD></TR>
+<TR><TD >viz.py</TD><TD > real-time viz from GL tool in <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A></TD></TR>
+<TR><TD >vizplotgui.py</TD><TD > combination of viz.py and plot.py and gui.py 
+</TD></TR></TABLE></DIV>
+
+<P>See the python/README file for instructions on how to run them and the
+source code for individual scripts for comments about what they do.
+</P>
+
+
+</HTML>
diff --git a/doc/Section_python.txt b/doc/Section_python.txt
new file mode 100644
index 0000000000..0f02c3a247
--- /dev/null
+++ b/doc/Section_python.txt
@@ -0,0 +1,610 @@
+"Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_errors.html :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+9. Python interface to LAMMPS :h3
+
+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.
+
+"Python"_http://www.python.org 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
+section"_Section_howto.html#4_10 of the manual and the couple
+directory of the distribution for more ideas about coupling LAMMPS to
+other codes.  See "this section"_Section_start.html#2_4 about how to
+build LAMMPS as a library, and "this section"_Section_howto.html#4_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.
+
+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.
+
+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.
+
+Thus you should first decide how you intend to use LAMMPS from Python.
+There are 3 options:
+
+(1) Use LAMMPS on a single processor running Python.
+
+(2) Use LAMMPS in parallel, where each processor runs Python, but your
+Python program does not use MPI.
+
+(3) Use LAMMPS in parallel, where each processor runs Python, and your
+Python script also makes MPI calls through a Python/MPI interface.
+
+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.
+
+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.
+
+"Extending Python with a serial version of LAMMPS"_#9_1
+"Creating a shared MPI library"_#9_2
+"Extending Python with a parallel version of LAMMPS"_#9_3
+"Extending Python with MPI"_#9_4
+"Testing the Python-LAMMPS interface"_#9_5
+"Using LAMMPS from Python"_#9_6
+"Example Python scripts that use LAMMPS"_#9_7 :ul
+
+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
+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#2_3 of the manual for a discussion of
+LAMMPS pacakges.  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.
+
+:line
+:line
+
+Extending Python with a serial version of LAMMPS :link(9_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".
+
+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
+
+Creating a shared MPI library :link(9_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-sharedlib=gcc
+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
+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 will typically fail if the linker uses libmpich.so
+instead.  This means you will need to remove the file
+/usr/local/lib/libmich.so before building LAMMPS again as a
+stand-alone code.
+
+:line
+
+Extending Python with a parallel version of LAMMPS :link(9_3),h4
+
+From the python directory, type
+
+python setup.py build :pre
+
+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
+
+Extending Python with MPI :link(9_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.
+
+These include
+
+"pyMPI"_http://pympi.sourceforge.net/
+"maroonmpi"_http://code.google.com/p/maroonmpi/
+"mpi4py"_http://code.google.com/p/mpi4py/
+"myMPI"_http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16
+"Pypar"_http://datamining.anu.edu.au/~ole/pypar :ul
+
+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
+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
+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.
+
+The one I recommend, since I have successfully used it with LAMMPS, is
+Pypar.  Pypar requires the ubiquitous "Numpy
+package"_http://numpy.scipy.org be installed in your Python.  After
+launching python, type
+
+>>> import numpy :pre
+
+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
+top-level directory, type
+
+python setup.py build
+sudo python setup.py install :pre
+
+The "sudo" is only needed if required to copy Numpy files into your
+Python distribution's site-packages directory.
+
+To install Pypar (version pypar-2.1.0_66 as of April 2009), unpack it
+and from its "source" directory, type
+
+python setup.py build
+sudo python setup.py install :pre
+
+Again, the "sudo" is only needed if required to copy PyPar files into
+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 :pre
+
+without error.  You should also be able to run python in parallel
+on a simple test script
+
+% mpirun -np 4 python test.script :pre
+
+where test.script contains the lines
+
+import pypar
+print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) :pre
+
+and see one line of output for each processor you ran on.
+
+:line
+
+Testing the Python-LAMMPS interface :link(9_5),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
+
+>>> from lammps import lammps
+>>> lmp = lammps() :pre
+
+If you get no errors, you're ready to use serial 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
+
+where test.script contains the lines
+
+import pypar
+from lammps import lammps
+lmp = lammps()
+print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()), lmp
+pypar.finalize() :pre
+
+Again, if you get no errors, you're good to go.
+
+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.
+
+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
+pypar.finalize(), to insure MPI is shut down correctly.
+
+Also note that a Python script can be invoked in one of several ways:
+
+% python foo.script
+% python -i foo.script
+% foo.script
+
+The last command requires that the first line of the script be
+something like this:
+
+#!/usr/local/bin/python 
+#!/usr/local/bin/python -i
+
+where the path points to where you have Python installed, and that you
+have made the script file executable:
+
+% chmod +x foo.script
+
+Without the "-i" flag, Python will exit when the script finishes.
+With the "-i" flag, you will be left in the Python interpreter when
+the script finishes, so you can type subsequent commands.  As
+mentioned above, you can only run Python interactively when running
+Python on a single processor, not in parallel.
+
+:line
+:line
+
+Using LAMMPS from Python :link(9_6),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
+"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:
+
+from lammps import lammps 
+from lammps import LMPINT as INT
+from lammps import LMPDOUBLE as DOUBLE
+from lammps import LMPIPTR as IPTR
+from lammps import LMPDPTR as DPTR
+from lammps import LMPDPTRPTR as DPTRPTR :pre
+
+These are the methods defined by the lammps module.  If you look
+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"\] :pre
+
+lmp.close()              # destroy a LAMMPS object :pre
+
+lmp.file(file)           # run an entire input script, file = "in.lj"
+lmp.command(cmd)         # invoke a single LAMMPS command, cmd = "run 100" :pre
+
+xlo = lmp.extract_global(name,type)  # extract a global quantity
+                                     # name = "boxxlo", "nlocal", etc
+				     # type = INT or DOUBLE :pre
+
+coords = lmp.extract_atom(name,type)      # extract a per-atom quantity
+                                          # name = "x", "type", etc
+				          # type = IPTR or DPTR or DPTRPTR :pre
+
+eng = 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
+					  # style = 0 = global data
+					  #	    1 = per-atom data
+					  #         2 = local data
+					  # type = 0 = scalar
+					  #	   1 = vector
+					  #        2 = array
+					  # i,j = indices of value in global vector or array :pre
+
+var = lmp.extract_variable(name,group,flag)  # extract value(s) from a variable
+	                                     # name = name of variable
+					     # group = group ID (ignored for equal-style variables)
+					     # flag = 0 = equal-style variable
+					     #        1 = atom-style variable :pre
+
+natoms = lmp.get_natoms()                 # total # of atoms as int
+x = lmp.get_coords()                      # return coords of all atoms in x
+lmp.put_coords(x)                         # set all atom coords via x :pre
+
+:line
+
+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.
+
+The file() and command() methods allow an input script or single
+commands to be invoked.
+
+The extract_global(), extract_atom(), extract_compute(),
+extract_fix(), and extract_variable() methods return values or
+pointers to data structures internal to LAMMPS.
+
+For extract_global() see the src/library.cpp file for the list of
+valid names.  New names could easily be added.  A double or integer is
+returned.  You need to specify the appropriate data type via the type
+argument.
+
+For extract_atom(), a pointer to internal LAMMPS atom-based data is
+returned, which you can use via normal Python subscripting.  See the
+extract() method in the src/atom.cpp file for a list of valid names.
+Again, new names could easily be added.  A pointer to a vector of
+doubles or integers, or a pointer to an array of doubles (double **)
+is returned.  You need to specify the appropriate data type via the
+type argument.
+
+For extract_compute() and extract_fix(), the global, per-atom, or
+local data calulated by the compute or fix can be accessed.  What is
+returned depends on whether the compute or fix calculates a scalar or
+vector or array.  For a scalar, a single double value is returned.  If
+the compute or fix calculates a vector or array, a pointer to the
+internal LAMMPS data is returned, which you can use via normal Python
+subscripting.  The one exception is that for a fix that calculates a
+global vector or array, a single double value from the vector or array
+is returned, indexed by I (vector) or I and J (array).  I,J are
+zero-based indices.  The I,J arguments can be left out if not needed.
+See "this section"_Section_howto.html#4_15 of the manual for a
+discussion of global, per-atom, and local data, and of scalar, vector,
+and array data types.  See the doc pages for individual
+"computes"_compute.html and "fixes"_fix.html for a description of what
+they calculate and store.
+
+For extract_variable(), an "equal-style or atom-style
+variable"_variable.html is evaluated and its result returned.
+
+For equal-style variables a single double value is returned and the
+group argument is ignored.  For atom-style variables, a vector of
+doubles is returned, one value per atom, which you can use via normal
+Python subscripting. The values will be zero for atoms not in the
+specified group.
+
+The get_natoms() method returns the total number of atoms in the
+simulation, as an int.  Note that extract_global("natoms") returns the
+same value, but as a double, which is the way LAMMPS stores it to
+allow for systems with more atoms than can be stored in an int (> 2
+billion).
+
+The get_coords() method returns an ctypes vector of doubles of length
+3*natoms, for the coordinates of all the atoms in the simulation,
+ordered by x,y,z and then by atom ID (see code for put_coords()
+below).  The array can be used via normal Python subscripting.  If
+atom IDs are not consecutively ordered within LAMMPS, a None is
+returned as indication of an error.
+
+Note that the data structure get_coords() returns is different from
+the data structure returned by extract_atom("x") in four ways.  (1)
+Get_coords() returns a vector which you index as x\[i\];
+extract_atom() returns an array which you index as x\[i\]\[j\].  (2)
+Get_coords() orders the atoms by atom ID while extract_atom() does
+not.  (3) Get_coords() returns a list of all atoms in the simulation;
+extract_atoms() returns just the atoms local to each processor.  (4)
+Finally, the get_coords() data structure is a copy of the atom coords
+stored internally in LAMMPS, whereas extract_atom returns an array
+that points directly to the internal data.  This means you can change
+values inside LAMMPS from Python by assigning a new values to the
+extract_atom() array.  To do this with the get_atoms() vector, you
+need to change values in the vector, then invoke the put_coords()
+method.
+
+The put_coords() method takes a vector of coordinates for all atoms in
+the simulation, assumed to be ordered by x,y,z and then by atom ID,
+and uses the values to overwrite the corresponding coordinates for
+each atom inside LAMMPS.  This requires LAMMPS to have its "map"
+option enabled; see the "atom_modify"_atom_modify.html command for
+details.  If it is not or if atom IDs are not consecutively ordered,
+no coordinates are reset,
+
+The array of coordinates passed to put_coords() must be a ctypes
+vector of doubles, allocated and initialized something like this:
+
+from ctypes import *
+natoms = lmp.get_atoms()
+n3 = 3*natoms
+x = (c_double*n3)()
+x[0] = x coord of atom with ID 1
+x[1] = y coord of atom with ID 1
+x[2] = z coord of atom with ID 1
+x[3] = x coord of atom with ID 2
+...
+x[n3-1] = z coord of atom with ID natoms
+lmp.put_coords(x) :pre
+
+Alternatively, you can just change values in the vector returned by
+get_coords(), since it is a ctypes vector of doubles.
+
+:line 
+
+As noted above, these Python class methods correspond one-to-one with
+the functions in the LAMMPS library interface in src/library.cpp and
+library.h.  This means you can extend the Python wrapper via the
+following steps:
+
+Add a new interface function to src/library.cpp and
+src/library.h. :ulb,l
+
+Verify the new function is syntactically correct by building LAMMPS as
+a library - see "this section"_Section_start.html#2_4 of the
+manual. :l
+
+Add a wrapper method in the Python LAMMPS module to python/lammps.py
+for this interface 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
+Python script.  Isn't ctypes amazing? :l,ule
+
+:line
+:line
+
+Example Python scripts that use LAMMPS :link(9_7),h4
+
+These are the Python scripts included as demos in the python/examples
+directory of the LAMMPS distribution, to illustrate the kinds of
+things that are possible when Python wraps LAMMPS.  If you create your
+own scripts, send them to us and we can include them in the LAMMPS
+distribution.
+
+trivial.py, read/run a LAMMPS input script via Python,
+demo.py, invoke various LAMMPS library interface routines,
+simple.py, mimic operation of couple/simple/simple.cpp in Python,
+gui.py, GUI go/stop/temperature-slider to control LAMMPS,
+plot.py, real-time temeperature plot with GnuPlot via "Pizza.py"_pizza,
+viz.py, real-time viz from GL tool in "Pizza.py"_pizza,
+vizplotgui.py, combination of viz.py and plot.py and gui.py :tb(c=2)
+
+See the python/README file for instructions on how to run them and the
+source code for individual scripts for comments about what they do.
+
+:link(pizza,http://www.sandia.gov/~sjplimp/pizza.html)
diff --git a/doc/Section_start.html b/doc/Section_start.html
index b77f25de85..41a45d5170 100644
--- a/doc/Section_start.html
+++ b/doc/Section_start.html
@@ -577,36 +577,24 @@ another application can link to.
 <P>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
 namespace; you can safely use any of its classes and methods from
-within your application code, as needed.  See the sample code
-examples/couple/c++_driver.cpp as an example.
+within your application code, as needed. 
 </P>
 <P>When used from a C or Fortran program or a scripting language, the
-library has a simple function-style interface, provided in library.cpp
-and library.h.  See the sample code examples/couple/c_driver.cpp as an
-example.
+library has a simple function-style interface, provided in
+src/library.cpp and src/library.h.
 </P>
-<P>You can add as many functions as you wish to library.cpp and
-library.h.  In a general sense, those functions can access LAMMPS data
-and return it to the caller or set LAMMPS data values as specified by
-the caller.  These 4 functions are currently included in library.cpp:
+<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#4_10">this section</A> of the manual.
+See <A HREF = "Section_python.html">this section</A> of the manual for a description
+of the Python wrapper provided with LAMMPS that operates through the
+LAMMPS library interface.
 </P>
-<PRE>void lammps_open(int, char **, MPI_Comm, void **ptr);
-void lammps_close(void *ptr);
-int lammps_file(void *ptr, char *);
-int lammps_command(void *ptr, char *); 
-</PRE>
-<P>The lammps_open() function is used to initialize LAMMPS, passing in a
-list of strings as if they were <A HREF = "#2_6">command-line arguments</A> when
-LAMMPS is run from the command line and a MPI communicator for LAMMPS
-to run under.  It returns a ptr to the LAMMPS object that is created,
-and which should be used in subsequent library calls.  Note that
-lammps_open() can be called multiple times to create multiple LAMMPS
-objects.
-</P>
-<P>The lammps_close() function is used to shut down LAMMPS and free all
-its memory.  The lammps_file() and lammps_command() functions are used
-to pass a file or string to LAMMPS as if it were an input file or
-single command read from an input script.
+<P>The files src/library.cpp and library.h contain the C-style interface
+to LAMMPS.  See <A HREF = "Section_howto.html#4_19">this section</A> of the manual
+for a description of the interface and how to extend it for your
+needs.
 </P>
 <HR>
 
diff --git a/doc/Section_start.txt b/doc/Section_start.txt
index d40621b07a..3fc685cd25 100644
--- a/doc/Section_start.txt
+++ b/doc/Section_start.txt
@@ -570,36 +570,24 @@ 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
 namespace; you can safely use any of its classes and methods from
-within your application code, as needed.  See the sample code
-examples/couple/c++_driver.cpp as an example.
+within your application 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 library.cpp
-and library.h.  See the sample code examples/couple/c_driver.cpp as an
-example.
+library has a simple function-style interface, provided in
+src/library.cpp and src/library.h.
 
-You can add as many functions as you wish to library.cpp and
-library.h.  In a general sense, those functions can access LAMMPS data
-and return it to the caller or set LAMMPS data values as specified by
-the caller.  These 4 functions are currently included in library.cpp:
+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 "this section"_Section_howto.html#4_10 of the manual.
+See "this section"_Section_python.html of the manual for a description
+of the Python wrapper provided with LAMMPS that operates through the
+LAMMPS library interface.
 
-void lammps_open(int, char **, MPI_Comm, void **ptr);
-void lammps_close(void *ptr);
-int lammps_file(void *ptr, char *);
-int lammps_command(void *ptr, char *); :pre
-
-The lammps_open() function is used to initialize LAMMPS, passing in a
-list of strings as if they were "command-line arguments"_#2_6 when
-LAMMPS is run from the command line and a MPI communicator for LAMMPS
-to run under.  It returns a ptr to the LAMMPS object that is created,
-and which should be used in subsequent library calls.  Note that
-lammps_open() can be called multiple times to create multiple LAMMPS
-objects.
-
-The lammps_close() function is used to shut down LAMMPS and free all
-its memory.  The lammps_file() and lammps_command() functions are used
-to pass a file or string to LAMMPS as if it were an input file or
-single command read from an input script.
+The files src/library.cpp and library.h contain the C-style interface
+to LAMMPS.  See "this section"_Section_howto.html#4_19 of the manual
+for a description of the interface and how to extend it for your
+needs.
 
 :line
 
diff --git a/doc/read_restart.html b/doc/read_restart.html
index 212ffd4196..c4482276f5 100644
--- a/doc/read_restart.html
+++ b/doc/read_restart.html
@@ -43,7 +43,7 @@ these cases.  Certain fixes will also not restart exactly, though they
 should provide statistically similar results.  These include <A HREF = "fix_shake.html">fix
 shake</A> and <A HREF = "fix_langevin.html">fix langevin</A>.  If a
 restarted run is immediately different than the run which produced the
-restart file, it could be a LAMMPS bug, so consider <A HREF = "Section_errors.html#9_2">reporting
+restart file, it could be a LAMMPS bug, so consider <A HREF = "Section_errors.html#10_2">reporting
 it</A> if you think the behavior is wrong.
 </P>
 <P>Because restart files are binary, they may not be portable to other
diff --git a/doc/read_restart.txt b/doc/read_restart.txt
index 938532964a..4e19976db3 100644
--- a/doc/read_restart.txt
+++ b/doc/read_restart.txt
@@ -41,7 +41,7 @@ should provide statistically similar results.  These include "fix
 shake"_fix_shake.html and "fix langevin"_fix_langevin.html.  If a
 restarted run is immediately different than the run which produced the
 restart file, it could be a LAMMPS bug, so consider "reporting
-it"_Section_errors.html#9_2 if you think the behavior is wrong.
+it"_Section_errors.html#10_2 if you think the behavior is wrong.
 
 Because restart files are binary, they may not be portable to other
 machines.  They can be converted to ASCII data files using the