git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8651 f3b2605a-c512-4ea7-a41b-209d697bcdaa

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>
+<UL><LI>11.1 <A HREF = "#py_1">Building LAMMPS as a shared library</A>
-<LI>11.2 <A HREF = "#py_2">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 
+<A NAME = "py_1"></A><H4>11.1 Building LAMMPS as a shared library 
-</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 
 </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
+more details, especially if your LAMMPS build uses auxiliary libraries
-libraries, e.g. ones required by certain packages and found in the
+like MPI or FFTW which may not be built as shared libraries on your
-lib/package directories.
+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>
 

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.1 "Building LAMMPS as a shared library"_#py_1
-11.2 "Building LAMMPS as a shared library"_#py_2
+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
+11.1 Building LAMMPS as a shared library :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
 
 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
+more details, especially if your LAMMPS build uses auxiliary libraries
-libraries, e.g. ones required by certain packages and found in the
+like MPI or FFTW which may not be built as shared libraries on your
-lib/package directories.
+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
 

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
+platform before making LAMMPS itself.  To build from the src
-library, from the src directory, type "make stubs", or from the STUBS
+directory, type "make stubs", or from the STUBS dir, type "make".
-dir, type "make" and it should create a libmpi_stubs.a suitable for
+This should create a libmpi_stubs.a file suitable for linking to
-linking to LAMMPS.  To build it as a shared library, from the STUBS
+LAMMPS.  If the build fails, you will need to edit the STUBS/Makefile
-dir, type "make shlib" and it should create a libmpi_stubs.so suitable
+for your platform.
-for dynamically loading when LAMMPS runs.  If either of these builds
-fail, 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
+liblmp_foo.so which another application can link to dyamically.  It
-well as a soft link liblmp.so, which the Python wrapper uses by
+will also create a soft link liblmp.so, which the Python wrapper uses
-default.
+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
+libraries.  This will be the case for libraries included with LAMMPS,
-LAMMPS, this includes all libraries needed by main LAMMPS (e.g. MPI or
+such as the dummy MPI library in src/STUBS or any package libraries in
-FFTW or JPEG), system libraries needed by main LAMMPS (e.g. extra libs
+lib/packges, since they are always built as shared libraries with the
-needed by MPI), any packages you have installed that require libraries
+-fPIC switch.  However, if a library like MPI or FFTW does not exist
-provided with LAMMPS (e.g. the USER-ATC package require
+as a shared library, the second make command will generate an error.
-lib/atc/libatc.so), and any system libraries (e.g. BLAS or
+This means you will need to install a shared library version of the
-Fortran-to-C libraries) listed in the lib/package/Makefile.lammps
+package.  The build instructions for the library should tell you how
-file.
+to do this.
-</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.
 </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
+<H5><B>Additional requirement for using a shared library:</B> 
-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>
 <P>The operating system finds shared libraries to load at run-time using
-the environment variable LD_LIBRARY_PATH.  So at a minimum you
+the environment variable LD_LIBRARY_PATH.  So you may wish
-must set it to include the lammps src directory where the LAMMPS
+to copy the file src/liblmp.so or src/liblmp_g++.so (for example)
-shared library file is created.
+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

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
+platform before making LAMMPS itself.  To build from the src
-library, from the src directory, type "make stubs", or from the STUBS
+directory, type "make stubs", or from the STUBS dir, type "make".
-dir, type "make" and it should create a libmpi_stubs.a suitable for
+This should create a libmpi_stubs.a file suitable for linking to
-linking to LAMMPS.  To build it as a shared library, from the STUBS
+LAMMPS.  If the build fails, you will need to edit the STUBS/Makefile
-dir, type "make shlib" and it should create a libmpi_stubs.so suitable
+for your platform.
-for dynamically loading when LAMMPS runs.  If either of these builds
-fail, 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
+liblmp_foo.so which another application can link to dyamically.  It
-well as a soft link liblmp.so, which the Python wrapper uses by
+will also create a soft link liblmp.so, which the Python wrapper uses
-default.
+by default.
-
-[Additional requirements for building a shared library:] :h5
 
 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
+libraries.  This will be the case for libraries included with LAMMPS,
-LAMMPS, this includes all libraries needed by main LAMMPS (e.g. MPI or
+such as the dummy MPI library in src/STUBS or any package libraries in
-FFTW or JPEG), system libraries needed by main LAMMPS (e.g. extra libs
+lib/packges, since they are always built as shared libraries with the
-needed by MPI), any packages you have installed that require libraries
+-fPIC switch.  However, if a library like MPI or FFTW does not exist
-provided with LAMMPS (e.g. the USER-ATC package require
+as a shared library, the second make command will generate an error.
-lib/atc/libatc.so), and any system libraries (e.g. BLAS or
+This means you will need to install a shared library version of the
-Fortran-to-C libraries) listed in the lib/package/Makefile.lammps
+package.  The build instructions for the library should tell you how
-file.
+to do this.
-
-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.
 
 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
+[Additional requirement for using a shared library:] :h5
-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
 
 The operating system finds shared libraries to load at run-time using
-the environment variable LD_LIBRARY_PATH.  So at a minimum you
+the environment variable LD_LIBRARY_PATH.  So you may wish
-must set it to include the lammps src directory where the LAMMPS
+to copy the file src/liblmp.so or src/liblmp_g++.so (for example)
-shared library file is created.
+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