From dd51b1a0c86ec544dcabf6b2fe2710d65f1e31b4 Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Tue, 14 Aug 2012 16:13:24 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8651
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/Section_python.html | 90 ++++++++++++++++++++++++-----------------
 doc/Section_python.txt  | 90 ++++++++++++++++++++++++-----------------
 doc/Section_start.html  | 81 ++++++++++---------------------------
 doc/Section_start.txt   | 81 ++++++++++---------------------------
 4 files changed, 150 insertions(+), 192 deletions(-)

diff --git a/doc/Section_python.html b/doc/Section_python.html
index 0b60c25101..9b69fe6fd1 100644
--- a/doc/Section_python.html
+++ b/doc/Section_python.html
@@ -14,8 +14,8 @@
 <P>This section describes how to build and use LAMMPS via a Python
 interface.
 </P>
-<UL><LI>11.1 <A HREF = "#py_1">Setting necessary environment variables</A>
-<LI>11.2 <A HREF = "#py_2">Building LAMMPS as a shared library</A>
+<UL><LI>11.1 <A HREF = "#py_1">Building LAMMPS as a shared library</A>
+<LI>11.2 <A HREF = "#py_2">Installing the Python wrapper into Python</A>
 <LI>11.3 <A HREF = "#py_3">Extending Python with MPI to run in parallel</A>
 <LI>11.4 <A HREF = "#py_4">Testing the Python-LAMMPS interface</A>
 <LI>11.5 <A HREF = "#py_5">Using LAMMPS from Python</A>
@@ -76,36 +76,7 @@ check which version of Python you have installed, by simply typing
 
 <HR>
 
-<A NAME = "py_1"></A><H4>11.1 Setting necessary environment variables 
-</H4>
-<P>For Python to use the LAMMPS interface, it needs to find two files.
-The paths to these files need to be added to two environment variables
-that Python checks.
-</P>
-<P>The first is the environment variable PYTHONPATH.  It needs
-to include the directory where the python/lammps.py file is.
-</P>
-<P>For the csh or tcsh shells, add something like this to your ~/.cshrc
-file:
-</P>
-<PRE>setenv PYTHONPATH $<I>PYTHONPATH</I>:/home/sjplimp/lammps/python 
-</PRE>
-<P>The second is the environment variable LD_LIBRARY_PATH, which is used
-by the operating system to find dynamic shared libraries when it loads
-them.  See the discussion in <A HREF = "Section_start.html#start_5">Section_start
-5</A> of the manual about building LAMMPS as a
-shared library, for instructions on how to set the LD_LIBRARY_PATH
-variable appropriately.
-</P>
-<P>If your LAMMPS build is not using any auxiliary libraries which are in
-non-default directories where the system cannot find them, you
-typically just need to add something like this to your ~/.cshrc file:
-</P>
-<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src 
-</PRE>
-<HR>
-
-<A NAME = "py_2"></A><H4>11.2 Building LAMMPS as a shared library 
+<A NAME = "py_1"></A><H4>11.1 Building LAMMPS as a shared library 
 </H4>
 <P>Instructions on how to build LAMMPS as a shared library are given in
 <A HREF = "Section_start.html#start_5">Section_start 5</A>.  A shared library is one
@@ -119,15 +90,62 @@ make -f Makefile.shlib foo
 </PRE>
 <P>where foo is the machine target name, such as linux or g++ or serial.
 This should create the file liblmp_foo.so in the src directory, as
-well as a soft link liblmp.so which is what the Python wrapper will
+well as a soft link liblmp.so, which is what the Python wrapper will
 load by default.  Note that if you are building multiple machine
 versions of the shared library, the soft link is always set to the
 most recently built version.
 </P>
 <P>If this fails, see <A HREF = "Section_start.html#start_5">Section_start 5</A> for
-more details, especially if your LAMMPS build uses auxiliary
-libraries, e.g. ones required by certain packages and found in the
-lib/package directories.
+more details, especially if your LAMMPS build uses auxiliary libraries
+like MPI or FFTW which may not be built as shared libraries on your
+system.
+</P>
+<HR>
+
+<A NAME = "py_2"></A><H4>11.2 Installing the Python wrapper into Python 
+</H4>
+<P>For Python to invoke LAMMPS, there are 2 files it needs to have:
+</P>
+<UL><LI>python/lammps.py
+<LI>src/liblmp.so 
+</UL>
+<P>Lammps.py is the Python wrapper on the LAMMPS library interface.
+Liblmp.so is the shared LAMMPS library that Python loads, as described
+above.
+</P>
+<P>You can insure Python can find these files in one of two ways:
+</P>
+<UL><LI>set two environment variables
+<LI>run the python/install.py script 
+</UL>
+<P>If you set the paths to these files as environment variables, you only
+have to do it once.  For the csh or tcsh shells, add something like
+this to your ~/.cshrc file, one line for each of the two files:
+</P>
+<PRE>setenv PYTHONPATH $<I>PYTHONPATH</I>:/home/sjplimp/lammps/python
+setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src 
+</PRE>
+<P>If you run the python/install.py script, you need to rerun it every
+time you rebuild LAMMPS (as a shared library) or make changes to the
+python/lammps.py file.
+</P>
+<P>You can invoke install.py from the python directory as
+</P>
+<PRE>% python install.py 
+</PRE>
+<P>Prefix this command with "sudo" if it does not allow you to copy files
+into the Python site-packages directory.  If you do this, make sure
+that the Python run by root is the same as the Python you run.
+E.g. you may need to do something like
+</P>
+<PRE>% sudo /usr/local/bin/python install.py 
+</PRE>
+<P>You can also invoke install.py from the src directory as
+</P>
+<PRE>% make install-python 
+</PRE>
+<P>Again, you may need to prefix this with "sudo".  In this mode you
+cannot control which Python root invokes.
 </P>
 <HR>
 
diff --git a/doc/Section_python.txt b/doc/Section_python.txt
index 8041bf10c4..db9f034e32 100644
--- a/doc/Section_python.txt
+++ b/doc/Section_python.txt
@@ -11,8 +11,8 @@
 This section describes how to build and use LAMMPS via a Python
 interface.
 
-11.1 "Setting necessary environment variables"_#py_1
-11.2 "Building LAMMPS as a shared library"_#py_2
+11.1 "Building LAMMPS as a shared library"_#py_1
+11.2 "Installing the Python wrapper into Python"_#py_2
 11.3 "Extending Python with MPI to run in parallel"_#py_3
 11.4 "Testing the Python-LAMMPS interface"_#py_4
 11.5 "Using LAMMPS from Python"_#py_5
@@ -72,36 +72,7 @@ check which version of Python you have installed, by simply typing
 :line
 :line
 
-11.1 Setting necessary environment variables :link(py_1),h4
-
-For Python to use the LAMMPS interface, it needs to find two files.
-The paths to these files need to be added to two environment variables
-that Python checks.
-
-The first is the environment variable PYTHONPATH.  It needs
-to include the directory where the python/lammps.py file is.
-
-For the csh or tcsh shells, add something like this to your ~/.cshrc
-file:
-
-setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python :pre
-
-The second is the environment variable LD_LIBRARY_PATH, which is used
-by the operating system to find dynamic shared libraries when it loads
-them.  See the discussion in "Section_start
-5"_Section_start.html#start_5 of the manual about building LAMMPS as a
-shared library, for instructions on how to set the LD_LIBRARY_PATH
-variable appropriately.
-
-If your LAMMPS build is not using any auxiliary libraries which are in
-non-default directories where the system cannot find them, you
-typically just need to add something like this to your ~/.cshrc file:
-
-setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
-
-:line
-
-11.2 Building LAMMPS as a shared library :link(py_2),h4
+11.1 Building LAMMPS as a shared library :link(py_1),h4
 
 Instructions on how to build LAMMPS as a shared library are given in
 "Section_start 5"_Section_start.html#start_5.  A shared library is one
@@ -115,15 +86,62 @@ make -f Makefile.shlib foo :pre
 
 where foo is the machine target name, such as linux or g++ or serial.
 This should create the file liblmp_foo.so in the src directory, as
-well as a soft link liblmp.so which is what the Python wrapper will
+well as a soft link liblmp.so, which is what the Python wrapper will
 load by default.  Note that if you are building multiple machine
 versions of the shared library, the soft link is always set to the
 most recently built version.
 
 If this fails, see "Section_start 5"_Section_start.html#start_5 for
-more details, especially if your LAMMPS build uses auxiliary
-libraries, e.g. ones required by certain packages and found in the
-lib/package directories.
+more details, especially if your LAMMPS build uses auxiliary libraries
+like MPI or FFTW which may not be built as shared libraries on your
+system.
+
+:line
+
+11.2 Installing the Python wrapper into Python :link(py_2),h4
+
+For Python to invoke LAMMPS, there are 2 files it needs to have:
+
+python/lammps.py
+src/liblmp.so :ul
+
+Lammps.py is the Python wrapper on the LAMMPS library interface.
+Liblmp.so is the shared LAMMPS library that Python loads, as described
+above.
+
+You can insure Python can find these files in one of two ways:
+
+set two environment variables
+run the python/install.py script :ul
+
+If you set the paths to these files as environment variables, you only
+have to do it once.  For the csh or tcsh shells, add something like
+this to your ~/.cshrc file, one line for each of the two files:
+
+setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
+setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
+
+If you run the python/install.py script, you need to rerun it every
+time you rebuild LAMMPS (as a shared library) or make changes to the
+python/lammps.py file.
+
+You can invoke install.py from the python directory as
+
+% python install.py :pre
+
+Prefix this command with "sudo" if it does not allow you to copy files
+into the Python site-packages directory.  If you do this, make sure
+that the Python run by root is the same as the Python you run.
+E.g. you may need to do something like
+
+% sudo /usr/local/bin/python install.py :pre
+
+You can also invoke install.py from the src directory as
+
+% make install-python :pre
+
+Again, you may need to prefix this with "sudo".  In this mode you
+cannot control which Python root invokes.
 
 :line
 
diff --git a/doc/Section_start.html b/doc/Section_start.html
index 8fcdf944c2..e0150bf571 100644
--- a/doc/Section_start.html
+++ b/doc/Section_start.html
@@ -281,13 +281,11 @@ dummy MPI library provided in src/STUBS, since you don't need a true
 MPI library installed on your system.  See the
 src/MAKE/Makefile.serial file for how to specify the 3 MPI variables
 in this case.  You will also need to build the STUBS library for your
-platform before making LAMMPS itself.  To build it as a static
-library, from the src directory, type "make stubs", or from the STUBS
-dir, type "make" and it should create a libmpi_stubs.a suitable for
-linking to LAMMPS.  To build it as a shared library, from the STUBS
-dir, type "make shlib" and it should create a libmpi_stubs.so suitable
-for dynamically loading when LAMMPS runs.  If either of these builds
-fail, you will need to edit the STUBS/Makefile for your platform.
+platform before making LAMMPS itself.  To build from the src
+directory, type "make stubs", or from the STUBS dir, type "make".
+This should create a libmpi_stubs.a file suitable for linking to
+LAMMPS.  If the build fails, you will need to edit the STUBS/Makefile
+for your platform.
 </P>
 <P>The file STUBS/mpi.cpp provides a CPU timer function called
 MPI_Wtime() that calls gettimeofday() .  If your system doesn't
@@ -816,33 +814,20 @@ first "make" command will create a current Makefile.shlib with all the
 file names in your src dir.  The second "make" command will use it to
 build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS
 settings in src/MAKE/Makefile.foo.  The build will create the file
-liblmp_foo.so which another application can link to dyamically, as
-well as a soft link liblmp.so, which the Python wrapper uses by
-default.
+liblmp_foo.so which another application can link to dyamically.  It
+will also create a soft link liblmp.so, which the Python wrapper uses
+by default.
 </P>
-<H5><B>Additional requirements for building a shared library:</B> 
-</H5>
 <P>Note that for a shared library to be usable by a calling program, all
 the auxiliary libraries it depends on must also exist as shared
-libraries, and the operating system must be able to find them.  For
-LAMMPS, this includes all libraries needed by main LAMMPS (e.g. MPI or
-FFTW or JPEG), system libraries needed by main LAMMPS (e.g. extra libs
-needed by MPI), any packages you have installed that require libraries
-provided with LAMMPS (e.g. the USER-ATC package require
-lib/atc/libatc.so), and any system libraries (e.g. BLAS or
-Fortran-to-C libraries) listed in the lib/package/Makefile.lammps
-file.
-</P>
-<P>If one of these auxiliary libraries does not exist as a shared
-library, the second make command should generate a build error.  If a
-needed library is simply missing from the link list, this will not
-generate an error at build time, but will generate a run-time error
-when the library is loaded, so be sure all needed libraries are
-listed, just as they are when building LAMMPS as a stand-alone code.
-</P>
-<P>Note that if you install them yourself, some libraries, such as MPI,
-may not build by default as shared libraries.  The build instructions
-for the library should tell you how to do this.
+libraries.  This will be the case for libraries included with LAMMPS,
+such as the dummy MPI library in src/STUBS or any package libraries in
+lib/packges, since they are always built as shared libraries with the
+-fPIC switch.  However, if a library like MPI or FFTW does not exist
+as a shared library, the second make command will generate an error.
+This means you will need to install a shared library version of the
+package.  The build instructions for the library should tell you how
+to do this.
 </P>
 <P>As an example, here is how to build and install the <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH
 library</A>, a popular open-source version of MPI, distributed by
@@ -859,43 +844,19 @@ make install
 you do not have write privileges for /usr/local/lib.  The end result
 should be the file /usr/local/lib/libmpich.so.
 </P>
-<P>Also note that not all of the auxiliary libraries provided with LAMMPS
-include Makefiles in their lib directories suitable for building them
-as shared libraries.  Typically this simply requires 3 steps: (a)
-adding a -fPIC switch when files are compiled, (b) adding "-fPIC
--shared" switches when the library is linked with a C++ (or Fortran)
-compiler, and (c) creating an output target that ends in ".so", like
-libatc.o.  As we or others create and contribute these Makefiles, we
-will add them to the LAMMPS distribution.
-</P>
-<H5><B>Additional requirements for using a shared library:</B> 
+<H5><B>Additional requirement for using a shared library:</B> 
 </H5>
 <P>The operating system finds shared libraries to load at run-time using
-the environment variable LD_LIBRARY_PATH.  So at a minimum you
-must set it to include the lammps src directory where the LAMMPS
-shared library file is created.
+the environment variable LD_LIBRARY_PATH.  So you may wish
+to copy the file src/liblmp.so or src/liblmp_g++.so (for example)
+to a place the system can find it by default, such as /usr/local/lib,
+or you may wish to add the lammps src directory to LD_LIBRARY_PATH.
 </P>
 <P>For the csh or tcsh shells, you could add something like this to your
 ~/.cshrc file:
 </P>
 <PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src 
 </PRE>
-<P>If any auxiliary libraries, used by LAMMPS, are not in default places
-where the operating system can find them, then you also have to add
-their paths to the LD_LIBRARY_PATH environment variable.
-</P>
-<P>For example, if you are using the dummy MPI library provided in
-src/STUBS, and have built the file libmpi_stubs.so, you would add
-something like this to your ~/.cshrc file:
-</P>
-<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src/STUBS 
-</PRE>
-<P>If you are using the LAMMPS USER-ATC package, and have built the file
-lib/atc/libatc.so, you would add something like this to your ~/.cshrc
-file:
-</P>
-<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/lib/atc 
-</PRE>
 <H5><B>Calling the LAMMPS library:</B> 
 </H5>
 <P>Either flavor of library (static or shared0 allows one or more LAMMPS
diff --git a/doc/Section_start.txt b/doc/Section_start.txt
index e3c7400c20..74afbd7ce7 100644
--- a/doc/Section_start.txt
+++ b/doc/Section_start.txt
@@ -275,13 +275,11 @@ dummy MPI library provided in src/STUBS, since you don't need a true
 MPI library installed on your system.  See the
 src/MAKE/Makefile.serial file for how to specify the 3 MPI variables
 in this case.  You will also need to build the STUBS library for your
-platform before making LAMMPS itself.  To build it as a static
-library, from the src directory, type "make stubs", or from the STUBS
-dir, type "make" and it should create a libmpi_stubs.a suitable for
-linking to LAMMPS.  To build it as a shared library, from the STUBS
-dir, type "make shlib" and it should create a libmpi_stubs.so suitable
-for dynamically loading when LAMMPS runs.  If either of these builds
-fail, you will need to edit the STUBS/Makefile for your platform.
+platform before making LAMMPS itself.  To build from the src
+directory, type "make stubs", or from the STUBS dir, type "make".
+This should create a libmpi_stubs.a file suitable for linking to
+LAMMPS.  If the build fails, you will need to edit the STUBS/Makefile
+for your platform.
 
 The file STUBS/mpi.cpp provides a CPU timer function called
 MPI_Wtime() that calls gettimeofday() .  If your system doesn't
@@ -810,33 +808,20 @@ first "make" command will create a current Makefile.shlib with all the
 file names in your src dir.  The second "make" command will use it to
 build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS
 settings in src/MAKE/Makefile.foo.  The build will create the file
-liblmp_foo.so which another application can link to dyamically, as
-well as a soft link liblmp.so, which the Python wrapper uses by
-default.
-
-[Additional requirements for building a shared library:] :h5
+liblmp_foo.so which another application can link to dyamically.  It
+will also create a soft link liblmp.so, which the Python wrapper uses
+by default.
 
 Note that for a shared library to be usable by a calling program, all
 the auxiliary libraries it depends on must also exist as shared
-libraries, and the operating system must be able to find them.  For
-LAMMPS, this includes all libraries needed by main LAMMPS (e.g. MPI or
-FFTW or JPEG), system libraries needed by main LAMMPS (e.g. extra libs
-needed by MPI), any packages you have installed that require libraries
-provided with LAMMPS (e.g. the USER-ATC package require
-lib/atc/libatc.so), and any system libraries (e.g. BLAS or
-Fortran-to-C libraries) listed in the lib/package/Makefile.lammps
-file.
-
-If one of these auxiliary libraries does not exist as a shared
-library, the second make command should generate a build error.  If a
-needed library is simply missing from the link list, this will not
-generate an error at build time, but will generate a run-time error
-when the library is loaded, so be sure all needed libraries are
-listed, just as they are when building LAMMPS as a stand-alone code.
-
-Note that if you install them yourself, some libraries, such as MPI,
-may not build by default as shared libraries.  The build instructions
-for the library should tell you how to do this.
+libraries.  This will be the case for libraries included with LAMMPS,
+such as the dummy MPI library in src/STUBS or any package libraries in
+lib/packges, since they are always built as shared libraries with the
+-fPIC switch.  However, if a library like MPI or FFTW does not exist
+as a shared library, the second make command will generate an error.
+This means you will need to install a shared library version of the
+package.  The build instructions for the library should tell you how
+to do this.
 
 As an example, here is how to build and install the "MPICH
 library"_mpich, a popular open-source version of MPI, distributed by
@@ -853,43 +838,19 @@ You may need to use "sudo make install" in place of the last line if
 you do not have write privileges for /usr/local/lib.  The end result
 should be the file /usr/local/lib/libmpich.so.
 
-Also note that not all of the auxiliary libraries provided with LAMMPS
-include Makefiles in their lib directories suitable for building them
-as shared libraries.  Typically this simply requires 3 steps: (a)
-adding a -fPIC switch when files are compiled, (b) adding "-fPIC
--shared" switches when the library is linked with a C++ (or Fortran)
-compiler, and (c) creating an output target that ends in ".so", like
-libatc.o.  As we or others create and contribute these Makefiles, we
-will add them to the LAMMPS distribution.
-
-[Additional requirements for using a shared library:] :h5
+[Additional requirement for using a shared library:] :h5
 
 The operating system finds shared libraries to load at run-time using
-the environment variable LD_LIBRARY_PATH.  So at a minimum you
-must set it to include the lammps src directory where the LAMMPS
-shared library file is created.
+the environment variable LD_LIBRARY_PATH.  So you may wish
+to copy the file src/liblmp.so or src/liblmp_g++.so (for example)
+to a place the system can find it by default, such as /usr/local/lib,
+or you may wish to add the lammps src directory to LD_LIBRARY_PATH.
 
 For the csh or tcsh shells, you could add something like this to your
 ~/.cshrc file:
 
 setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
 
-If any auxiliary libraries, used by LAMMPS, are not in default places
-where the operating system can find them, then you also have to add
-their paths to the LD_LIBRARY_PATH environment variable.
-
-For example, if you are using the dummy MPI library provided in
-src/STUBS, and have built the file libmpi_stubs.so, you would add
-something like this to your ~/.cshrc file:
-
-setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src/STUBS :pre
-
-If you are using the LAMMPS USER-ATC package, and have built the file
-lib/atc/libatc.so, you would add something like this to your ~/.cshrc
-file:
-
-setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/atc :pre
-
 [Calling the LAMMPS library:] :h5
 
 Either flavor of library (static or shared0 allows one or more LAMMPS