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.
+The python source code in lammps.py is the Python wrapper on the
-Liblammps.so is the shared LAMMPS library that Python loads, as
+LAMMPS library interface. The liblammps.so or liblammps.dylib file
-described above.
+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
+set two environment variables pointing to the location in the source tree
-run the python/install.py script :ul
+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
+On MacOSX you may also need to set DYLD_LIBRARY_PATH accordingly.
-time you rebuild LAMMPS (as a shared library) or make changes to the
+For Bourne/Korn shells accordingly into the corresponding files using
-python/lammps.py file.
+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
+% python install.py -m \<python module\> -l <shared library> -v <version.h file> \[-d \<pydir\>\] :pre
-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.
 
-Note that libdir must be a location that is in your default
+The -m flag points to the lammps.py python module file to be installed,
-LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib.  And pydir must be a
+the -l flag points to the LAMMPS shared library file to be installed,
-location that Python looks in by default for imported modules, like
+the -v flag points to the version.h file in the LAMMPS source and the
-its site-packages dir.  If you want to copy these files to
+optional -d flag to the desired installation folder, if you don't want
-non-standard locations, such as within your own user space, you will
+the Python specific site-packages folder. If you want to copy these files to
-need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables
+non-standard locations, you will need to set your PYTHONPATH and
-accordingly, as above.
+LD_LIBRARY_PATH (and DYLD_LIBRARY_PATH) environment variables
-
+accordingly, as described 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.
 
 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"
+launch one or more simulations.  In Python lingo, this is called
-Python with LAMMPS.
+"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
+input script or styles can invoke Python code directly, and pass
-back-and-forth between the input script and Python functions you
+information back-and-forth between the input script and Python
-write.  This Python code can also callback to LAMMPS to query or change
+functions you write.  This Python code can also callback to LAMMPS
-its attributes.  In Python lingo, this is "embedding" Python in
+to query or change its attributes through the LAMMPS Python module
-LAMMPS.  When used in this mode, Python can perform operations that
+mentioned above.  In Python lingo, this is "embedding" Python in
-the simple LAMMPS input script syntax cannot.
+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: