changes to Errors and Python doc pages

doc/src/Python_test.txt

@@ -0,0 +1,131 @@
+"Higher level section"_Python.html - "LAMMPS WWW Site"_lws - "LAMMPS
+Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+Test the Python/LAMMPS interface :h3
+
+To test if LAMMPS is callable from Python, launch Python interactively
+and type:
+
+>>> from lammps import lammps
+>>> lmp = lammps() :pre
+
+If you get no errors, you're ready to use LAMMPS from Python.  If the
+2nd command fails, the most common error to see is
+
+OSError: Could not load LAMMPS dynamic library :pre
+
+which means Python was unable to load the LAMMPS shared library.  This
+typically occurs if the system can't find the LAMMPS shared library or
+one of the auxiliary shared libraries it depends on, or if something
+about the library is incompatible with your Python.  The error message
+should give you an indication of what went wrong.
+
+You can also test the load directly in Python as follows, without
+first importing from the lammps.py file:
+
+>>> from ctypes import CDLL
+>>> CDLL("liblammps.so") :pre
+
+If an error occurs, carefully go thru the steps in "Section
+2.4"_Section_start.html#start_4 and above about building a shared
+library and about insuring Python can find the necessary two files
+it needs.
+
+[Test LAMMPS and Python in serial:] :h4
+
+To run a LAMMPS test in serial, type these lines into Python
+interactively from the bench directory:
+
+>>> from lammps import lammps
+>>> lmp = lammps()
+>>> lmp.file("in.lj") :pre
+
+Or put the same lines in the file test.py and run it as
+
+% python test.py :pre
+
+Either way, you should see the results of running the in.lj benchmark
+on a single processor appear on the screen, the same as if you had
+typed something like:
+
+lmp_g++ -in in.lj :pre
+
+[Test LAMMPS and Python in parallel:] :h4
+
+To run LAMMPS in parallel, assuming you have installed the
+"PyPar"_https://github.com/daleroberts/pypar package as discussed
+above, create a test.py file containing these lines:
+
+import pypar
+from lammps import lammps
+lmp = lammps()
+lmp.file("in.lj")
+print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
+pypar.finalize() :pre
+
+To run LAMMPS in parallel, assuming you have installed the
+"mpi4py"_https://bitbucket.org/mpi4py/mpi4py package as discussed
+above, create a test.py file containing these lines:
+
+from mpi4py import MPI
+from lammps import lammps
+lmp = lammps()
+lmp.file("in.lj")
+me = MPI.COMM_WORLD.Get_rank()
+nprocs = MPI.COMM_WORLD.Get_size()
+print "Proc %d out of %d procs has" % (me,nprocs),lmp
+MPI.Finalize() :pre
+
+You can either script in parallel as:
+
+% mpirun -np 4 python test.py :pre
+
+and you should see the same output as if you had typed
+
+% mpirun -np 4 lmp_g++ -in in.lj :pre
+
+Note that if you leave out the 3 lines from test.py that specify PyPar
+commands you will instantiate and run LAMMPS independently on each of
+the P processors specified in the mpirun command.  In this case you
+should get 4 sets of output, each showing that a LAMMPS run was made
+on a single processor, instead of one set of output showing that
+LAMMPS ran on 4 processors.  If the 1-processor outputs occur, it
+means that PyPar is not working correctly.
+
+Also note that once you import the PyPar module, PyPar initializes MPI
+for you, and you can use MPI calls directly in your Python script, as
+described in the PyPar documentation.  The last line of your Python
+script should be pypar.finalize(), to insure MPI is shut down
+correctly.
+
+[Running Python scripts:] :h4
+
+Note that any Python script (not just for LAMMPS) can be invoked in
+one of several ways:
+
+% python foo.script
+% python -i foo.script
+% foo.script :pre
+
+The last command requires that the first line of the script be
+something like this:
+
+#!/usr/local/bin/python
+#!/usr/local/bin/python -i :pre
+
+where the path points to where you have Python installed, and that you
+have made the script file executable:
+
+% chmod +x foo.script :pre
+
+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.