partial documentation update

doc/src/Python_install.txt

@@ -12,16 +12,22 @@ Installing LAMMPS in Python :h3
 For Python to invoke LAMMPS, there are 2 files it needs to know about:
 
 python/lammps.py
-src/liblammps.so :ul
+liblammps.so or liblammps.dylib :ul
 
-Lammps.py is the Python wrapper on the LAMMPS library interface.
-Liblammps.so is the shared LAMMPS library that Python loads, as
-described above.
+The python source code in lammps.py is the Python wrapper on the
+LAMMPS library interface. The liblammps.so or liblammps.dylib file
+is the shared LAMMPS library that Python loads dynamically.
 
 You can insure Python can find these files in one of two ways:
 
-set two environment variables
-run the python/install.py script :ul
+set two environment variables pointing to the location in the source tree
+run "make install-python" or run the python/install.py script explicitly :ul
+
+When calling "make install-python" LAMMPS will try to install the
+python module and the shared library into the python site-packages folders;
+either the system-wide ones, or the local users ones (in case of unsufficient
+permissions for the global install). Python will then find the module
+and shared library file automatically.
 
 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
@@ -30,42 +36,28 @@ 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 use the python/install.py script, you need to invoke it every
-time you rebuild LAMMPS (as a shared library) or make changes to the
-python/lammps.py file.
+On MacOSX you may also need to set DYLD_LIBRARY_PATH accordingly.
+For Bourne/Korn shells accordingly into the corresponding files using
+the "export" shell builtin.
 
-You can invoke install.py from the python directory as
+If you use "make install-python" or the python/install.py script, you need
+to invoke it every time you rebuild LAMMPS (as a shared library) or
+make changes to the python/lammps.py file, so that the site-packages
+files are updated with the new version.
 
-% python install.py \[libdir\] \[pydir\] :pre
+If the default settings of "make install-python" are not what you want,
+you can invoke install.py from the python directory manually as
 
-The optional libdir is where to copy the LAMMPS shared library to; the
-default is /usr/local/lib.  The optional pydir is where to copy the
-lammps.py file to; the default is the site-packages directory of the
-version of Python that is running the install script.
+% python install.py -m \<python module\> -l <shared library> -v <version.h file> \[-d \<pydir\>\] :pre
 
-Note that libdir must be a location that is in your default
-LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib.  And pydir must be a
-location that Python looks in by default for imported modules, like
-its site-packages dir.  If you want to copy these files to
-non-standard locations, such as within your own user space, you will
-need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables
-accordingly, as above.
-
-If the install.py script does not allow you to copy files into system
-directories, prefix the python command with "sudo".  If you do this,
-make sure that the Python that root runs is the same as the Python you
-run.  E.g. you may need to do something like
-
-% sudo /usr/local/bin/python install.py \[libdir\] \[pydir\] :pre
-
-You can also invoke install.py from the make command in the src
-directory as
-
-% make install-python :pre
-
-In this mode you cannot append optional arguments.  Again, you may
-need to prefix this with "sudo".  In this mode you cannot control
-which Python is invoked by root.
+The -m flag points to the lammps.py python module file to be installed,
+the -l flag points to the LAMMPS shared library file to be installed,
+the -v flag points to the version.h file in the LAMMPS source and the
+optional -d flag to the desired installation folder, if you don't want
+the Python specific site-packages folder. If you want to copy these files to
+non-standard locations, you will need to set your PYTHONPATH and
+LD_LIBRARY_PATH (and DYLD_LIBRARY_PATH) environment variables
+accordingly, as described above.
 
 Note that if you want Python to be able to load different versions of
 the LAMMPS shared library (see "this section"_Python_shlib.html), you will

doc/src/Python_overview.txt

@@ -13,11 +13,11 @@ Overview of Python and LAMMPS :h3
 LAMMPS can work together with Python in three ways.  First, Python can
 wrap LAMMPS through the its "library interface"_Howto_library.html, so
 that a Python script can create one or more instances of LAMMPS and
-launch one or more simulations.  In Python lingo, this is "extending"
-Python with LAMMPS.
+launch one or more simulations.  In Python lingo, this is called
+"extending" Python with a LAMMPS module.
 
 Second, a lower-level Python interface can be used indirectly through
-provided PyLammps and IPyLammps wrapper classes, written in Python.
+the provided PyLammps and IPyLammps wrapper classes, written in Python.
 These wrappers try to simplify the usage of LAMMPS in Python by
 providing an object-based interface to common LAMMPS functionality.
 They also reduces the amount of code necessary to parameterize LAMMPS
@@ -25,11 +25,12 @@ scripts through Python and make variables and computes directly
 accessible.
 
 Third, LAMMPS can use the Python interpreter, so that a LAMMPS
-input script can invoke Python code directly, and pass information
-back-and-forth between the input script and Python functions you
-write.  This Python code can also callback to LAMMPS to query or change
-its attributes.  In Python lingo, this is "embedding" Python in
-LAMMPS.  When used in this mode, Python can perform operations that
-the simple LAMMPS input script syntax cannot.
+input script or styles can invoke Python code directly, and pass
+information back-and-forth between the input script and Python
+functions you write.  This Python code can also callback to LAMMPS
+to query or change its attributes through the LAMMPS Python module
+mentioned above.  In Python lingo, this is "embedding" Python in
+LAMMPS.  When used in this mode, Python can perform script operations
+that the simple LAMMPS input script syntax can not.
 
 

python/README

@@ -9,12 +9,12 @@ doc/Section_python.html and in doc/Section_start.html#start_5.
 Basically you need to follow these steps in the src directory:
 
 % make g++ mode=shlib           # build for whatever machine target you wish
-% make install-python           # may need to do this via sudo
+% make install-python           # install into site-packages folder
 
 You can replace the last step by a one-time setting of environment
 variables in your shell script.  Or you can run the python/install.py
 script directly to give you more control over where the two relevant
-files are installed.  See doc/Section_python.html for details.
+files are installed.  See doc/Python_install.html for details.
 
 You should then be able to launch Python and instantiate an instance
 of LAMMPS: