Merge pull request #287 from rbberger/pylammps/docs

Created PyLammps documentation

doc/src/Section_python.txt

@@ -8,19 +8,26 @@
 
 11. Python interface to LAMMPS :h3
 
-LAMMPS can work together with Python in two ways.  First, Python can
+LAMMPS can work together with Python in three ways.  First, Python can
 wrap LAMMPS through the "LAMMPS library
 interface"_Section_howto.html#howto_19, 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.
 
-Second, LAMMPS can use the Python interpreter, so that a LAMMPS input
+Second, the low-level Python interface can be used indirectly through the
+PyLammps and IPyLammps wrapper classes in Python. These wrappers try to
+simplify the usage of LAMMPS in Python by providing an object-based interface
+to common LAMMPS functionality. It also reduces the amount of code necessary to
+parameterize LAMMPS scripts through Python and makes variables and computes
+directly accessible. See "PyLammps interface"_#py_9 for more details.
+
+Third, LAMMPS can use the Python interpreter, so that a LAMMPS input
 script can invoke Python code, and pass information back-and-forth
 between the input script and Python functions you write.  The Python
 code can also callback to LAMMPS to query or change its attributes.
 In Python lingo, this is "embedding" Python in LAMMPS.
 
-This section describes how to do both.
+This section describes how to use these three approaches.
 
 11.1 "Overview of running LAMMPS from Python"_#py_1
 11.2 "Overview of using Python from a LAMMPS script"_#py_2
@@ -29,7 +36,8 @@ This section describes how to do both.
 11.5 "Extending Python with MPI to run in parallel"_#py_5
 11.6 "Testing the Python-LAMMPS interface"_#py_6
 11.7 "Using LAMMPS from Python"_#py_7
-11.8 "Example Python scripts that use LAMMPS"_#py_8 :ul
+11.8 "Example Python scripts that use LAMMPS"_#py_8
+11.9 "PyLammps interface"_#py_9 :ul
 
 If you are not familiar with it, "Python"_http://www.python.org is a
 powerful scripting and programming language which can essentially do
@@ -824,3 +832,7 @@ different visualization package options.  Click to see larger images:
 :image(JPG/screenshot_atomeye_small.jpg,JPG/screenshot_atomeye.jpg)
 :image(JPG/screenshot_pymol_small.jpg,JPG/screenshot_pymol.jpg)
 :image(JPG/screenshot_vmd_small.jpg,JPG/screenshot_vmd.jpg)
+
+11.9 PyLammps interface :link(py_9),h4
+
+Please see the "PyLammps Tutorial"_tutorial_pylammps.html.

doc/src/tutorial_pylammps.txt

@@ -0,0 +1,462 @@
+"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
+
+PyLammps Tutorial :h1
+
+<!-- RST
+.. contents::
+END_RST -->
+
+Overview :h2
+
+PyLammps is a Python wrapper class which can be created on its own or use an
+existing lammps Python object. It creates a simpler, Python-like interface to
+common LAMMPS functionality. Unlike the original flat C-types interface, it
+exposes a discoverable API. It no longer requires knowledge of the underlying
+C++ code implementation.  Finally, the IPyLammps wrapper builds on top of
+PyLammps and adds some additional features for IPython integration into IPython
+notebooks, e.g. for embedded visualization output from dump/image.
+
+Comparison of lammps and PyLammps interfaces :h3
+
+lammps.lammps :h4
+
+uses C-Types
+direct memory access to native C++ data
+provides functions to send and receive data to LAMMPS
+requires knowledge of how LAMMPS internally works (C pointers, etc) :ul
+
+lammps.PyLammps :h4
+
+higher-level abstraction built on top of original C-Types interface
+manipulation of Python objects
+communication with LAMMPS is hidden from API user 
+shorter, more concise Python
+better IPython integration, designed for quick prototyping :ul
+
+
+Quick Start :h2
+
+System-wide Installation :h3
+
+Step 1: Building LAMMPS as a shared library :h4
+
+To use LAMMPS inside of Python it has to be compiled as shared library. This
+library is then loaded by the Python interface. In this example, we use the
+Make.py utility to create a Makefile with C++ exceptions, PNG, JPEG and FFMPEG
+output support enabled. Finally, we also enable the MOLECULE package and compile
+using the generated {auto} Makefile.
+
+cd $LAMMPS_DIR/src :pre
+
+# generate custom Makefile
+python2 Make.py -jpg -png -s ffmpeg exceptions -m mpi -a file :pre
+
+# add packages if necessary
+make yes-MOLECULE :pre
+
+# compile shared library using Makefile
+make mode=shlib auto :pre
+
+Step 2: Installing the LAMMPS Python package :h4
+
+PyLammps is part of the lammps Python package. To install it simply install
+that package into your current Python installation.
+
+cd $LAMMPS_DIR/python
+python install.py :pre
+
+NOTE: Recompiling the shared library requires reinstalling the Python package
+
+
+Installation inside of a virtualenv :h3
+
+You can use virtualenv to create a custom Python environment specifically tuned
+for your workflow.
+
+Benefits of using a virtualenv :h4
+
+isolation of your system Python installation from your development installation
+installation can happen in your user directory without root access (useful for HPC clusters)
+installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum package managers (and without root access)
+you can even install specific old versions of a package if necessary :ul
+
+[Prerequisite (e.g. on Ubuntu)]
+
+apt-get install python-virtualenv :pre
+
+Creating a virtualenv with lammps installed :h4
+
+# create virtualenv name 'testing' :pre
+
+# activate 'testing' environment
+source testing/bin/activate :pre
+
+# install LAMMPS package in virtualenv
+(testing) cd $LAMMPS_DIR/python
+(testing) python install.py :pre
+
+# install other useful packages
+(testing) pip install matplotlib jupyter mpi4py :pre
+
+... :pre
+
+# return to original shell
+(testing) deactivate :pre
+
+
+Creating a new instance of PyLammps :h2
+
+To create a PyLammps object you need to first import the class from the lammps
+module. By using the default constructor, a new {lammps} instance is created.
+
+from lammps import PyLammps
+L = PyLammps() :pre
+
+You can also initialize PyLammps on top of this existing {lammps} object:
+
+from lammps import lammps, PyLammps
+lmp = lammps()
+L = PyLammps(ptr=lmp) :pre
+
+Commands :h2
+
+Sending a LAMMPS command with the existing library interfaces is done using
+the command method of the lammps object instance.
+
+For instance, let's take the following LAMMPS command:
+
+region box block 0 10 0 5 -0.5 0.5 :pre
+
+In the original interface this command can be executed with the following
+Python code if {L} was a lammps instance:
+
+L.command("region box block 0 10 0 5 -0.5 0.5") :pre
+
+With the PyLammps interface, any command can be split up into arbitrary parts
+separated by whitespace, passed as individual arguments to a region method.
+
+L.region("box block", 0, 10, 0, 5, -0.5, 0.5) :pre
+
+Note that each parameter is set as Python literal floating-point number. In the
+PyLammps interface, each command takes an arbitrary parameter list and transparently
+merges it to a single command string, separating individual parameters by whitespace.
+
+The benefit of this approach is avoiding redundant command calls and easier
+parameterization. In the original interface parametrization needed to be done
+manually by creating formatted strings.
+
+L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi)) :pre
+
+In contrast, methods of PyLammps accept parameters directly and will convert
+them automatically to a final command string.
+
+L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) :pre
+
+System state :h2
+
+In addition to dispatching commands directly through the PyLammps object, it
+also provides several properties which allow you to query the system state.
+
+:dlb
+
+L.system :dt
+
+Is a dictionary describing the system such as the bounding box or number of atoms :dd
+
+L.system.xlo, L.system.xhi :dt
+
+bounding box limits along x-axis :dd
+
+L.system.ylo, L.system.yhi :dt
+
+bounding box limits along y-axis :dd
+
+L.system.zlo, L.system.zhi :dt
+
+bounding box limits along z-axis :dd
+
+L.communication :dt
+
+configuration of communication subsystem, such as the number of threads or processors :dd
+
+L.communication.nthreads :dt
+
+number of threads used by each LAMMPS process :dd
+
+L.communication.nprocs :dt
+
+number of MPI processes used by LAMMPS :dd
+
+L.fixes :dt
+
+List of fixes in the current system :dd
+
+L.computes :dt
+
+List of active computes in the current system :dd
+
+L.dump :dt
+
+List of active dumps in the current system :dd
+
+L.groups :dt
+
+List of groups present in the current system :dd
+
+:dle
+
+Working with LAMMPS variables :h2
+
+LAMMPS variables can be both defined and accessed via the PyLammps interface.
+
+To define a variable you can use the "variable"_variable.html command:
+
+L.variable("a index 2") :pre
+
+A dictionary of all variables is returned by L.variables
+
+you can access an individual variable by retrieving a variable object from the
+L.variables dictionary by name
+
+a = L.variables\['a'\] :pre
+
+The variable value can then be easily read and written by accessing the value
+property of this object.
+
+print(a.value)
+a.value = 4 :pre
+
+Retrieving the value of an arbitrary LAMMPS expressions :h2
+
+LAMMPS expressions can be immediately evaluated by using the eval method. The
+passed string parameter can be any expression containing global thermo values,
+variables, compute or fix data.
+
+result = L.eval("ke") # kinetic energy
+result = L.eval("pe") # potential energy :pre
+
+result = L.eval("v_t/2.0") :pre
+
+Accessing atom data :h2
+
+All atoms in the current simulation can be accessed by using the L.atoms list.
+Each element of this list is an object which exposes its properties (id, type,
+position, velocity, force, etc.).
+
+# access first atom
+L.atoms\[0\].id
+L.atoms\[0\].type :pre
+
+# access second atom
+L.atoms\[1\].position
+L.atoms\[1\].velocity
+L.atoms\[1\].force :pre
+
+Some properties can also be used to set:
+
+# set position in 2D simulation
+L.atoms\[0\].position = (1.0, 0.0) :pre
+
+# set position in 3D simulation
+L.atoms\[0\].position = (1.0, 0.0, 1.) :pre
+
+Evaluating thermo data :h2
+
+Each simulation run usually produces thermo output based on system state,
+computes, fixes or variables. The trajectories of these values can be queried
+after a run via the L.runs list. This list contains a growing list of run data.
+The first element is the output of the first run, the second element that of
+the second run.
+
+L.run(1000)
+L.runs\[0\] # data of first 1000 time steps :pre
+
+L.run(1000)
+L.runs\[1\] # data of second 1000 time steps :pre
+
+Each run contains a dictionary of all trajectories. Each trajectory is
+accessible through its thermo name:
+
+L.runs\[0\].step # list of time steps in first run
+L.runs\[0\].ke   # list of kinetic energy values in first run :pre
+
+Together with matplotlib plotting data out of LAMMPS becomes simple:
+
+import matplotlib.plot as plt
+
+steps = L.runs\[0\].step
+ke    = L.runs\[0\].ke
+plt.plot(steps, ke) :pre
+
+Error handling with PyLammps :h2
+
+Compiling the shared library with C++ exception support provides a better error
+handling experience.  Without exceptions the LAMMPS code will terminate the
+current Python process with an error message.  C++ exceptions allow capturing
+them on the C++ side and rethrowing them on the Python side. This way you
+can handle LAMMPS errors through the Python exception handling mechanism.
+
+IMPORTANT NOTE: Capturing a LAMMPS exception in Python can still mean that the
+current LAMMPS process is in an illegal state and must be terminated. It is
+advised to save your data and terminate the Python instance as quickly as
+possible.
+
+Using PyLammps in IPython notebooks and Jupyter :h2
+
+If the LAMMPS Python package is installed for the same Python interpreter as
+IPython, you can use PyLammps directly inside of an IPython notebook inside of
+Jupyter. Jupyter is a powerful integrated development environment (IDE) for
+many dynamic languages like Python, Julia and others, which operates inside of
+any web browser. Besides auto-completion and syntax highlighting it allows you
+to create formatted documents using Markup, mathematical formulas, graphics and
+animations intermixed with executable Python code. It is a great format for
+tutorials and showcasing your latest research.
+
+To launch an instance of Jupyter simply run the following command inside your
+Python environment (this assumes you followed the Quick Start instructions):
+
+jupyter notebook :pre
+
+IPyLammps Examples :h2
+
+Examples of IPython notebooks can be found in the python/examples/pylammps
+subdirectory. To open these notebooks launch {jupyter notebook} inside this
+directory and navigate to one of them. If you compiled and installed 
+a LAMMPS shared library with execeptions, PNG, JPEG and FFMPEG support
+you should be able to rerun all of these notebooks.
+
+Validating a dihedral potential :h3
+
+This example showcases how an IPython Notebook can be used to compare a simple
+LAMMPS simulation of a harmonic dihedral potential to its analytical solution.
+Four atoms are placed in the simulation and the dihedral potential is applied on
+them using a datafile. Then one of the atoms is rotated along the central axis by
+setting its position from Python, which changes the dihedral angle.
+
+phi = \[d * math.pi / 180 for d in range(360)\] :pre
+
+pos = \[(1.0, math.cos(p), math.sin(p)) for p in phi\] :pre
+
+pe = \[\]
+for p in pos:
+    L.atoms\[3\].position = p
+    L.run(0)
+    pe.append(L.eval("pe")) :pre
+
+By evaluating the potential energy for each position we can verify that
+trajectory with the analytical formula.  To compare both solutions, we plot
+both trajectories over each other using matplotlib, which embeds the generated
+plot inside the IPython notebook.
+
+:c,image(JPG/pylammps_dihedral.jpg)
+
+Running a Monte Carlo relaxation :h3
+
+This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation
+simulation, computing and plotting energy terms and even embedding video output.
+
+Initially, a 2D system is created in a state with minimal energy.
+
+:c,image(JPG/pylammps_mc_minimum.jpg)
+
+It is then disordered by moving each atom by a random delta.
+
+random.seed(27848)
+deltaperturb = 0.2 :pre
+
+for i in range(L.system.natoms):
+    x, y = L.atoms\[i\].position
+    dx = deltaperturb * random.uniform(-1, 1)
+    dy = deltaperturb * random.uniform(-1, 1)
+    L.atoms\[i\].position  = (x+dx, y+dy) :pre
+
+L.run(0) :pre
+
+:c,image(JPG/pylammps_mc_disordered.jpg)
+
+Finally, the Monte Carlo algorithm is implemented in Python. It continuously
+moves random atoms by a random delta and only accepts certain moves.
+
+estart = L.eval("pe")
+elast = estart :pre
+
+naccept = 0
+energies = \[estart\] :pre
+
+niterations = 3000
+deltamove = 0.1
+kT = 0.05 :pre
+
+natoms = L.system.natoms :pre
+
+for i in range(niterations):
+    iatom = random.randrange(0, natoms)
+    current_atom = L.atoms\[iatom\] :pre
+    
+    x0, y0 = current_atom.position :pre
+    
+    dx = deltamove * random.uniform(-1, 1)
+    dy = deltamove * random.uniform(-1, 1) :pre
+    
+    current_atom.position = (x0+dx, y0+dy) :pre
+    
+    L.run(1, "pre no post no") :pre
+    
+    e = L.eval("pe")
+    energies.append(e) :pre
+    
+    if e <= elast:
+        naccept += 1
+        elast = e
+    elif random.random() <= math.exp(natoms*(elast-e)/kT):
+        naccept += 1
+        elast = e
+    else:
+        current_atom.position = (x0, y0) :pre
+
+The energies of each iteration are collected in a Python list and finally plotted using matplotlib.
+
+:c,image(JPG/pylammps_mc_energies_plot.jpg)
+
+The IPython notebook also shows how to use dump commands and embed video files
+inside of the IPython notebook.
+
+Using PyLammps and mpi4py (Experimental) :h2
+
+PyLammps can be run in parallel using mpi4py. This python package can be installed using
+
+pip install mpi4py :pre
+
+The following is a short example which reads in an existing LAMMPS input file and
+executes it in parallel.  You can find in.melt in the examples/melt folder.
+
+from mpi4py import MPI
+from lammps import PyLammps :pre
+
+L = PyLammps()
+L.file("in.melt") :pre
+
+if MPI.COMM_WORLD.rank == 0:
+    print("Potential energy: ", L.eval("pe")) :pre
+
+MPI.Finalize() :pre
+
+To run this script (melt.py) in parallel using 4 MPI processes we invoke the
+following mpirun command:
+
+mpirun -np 4 python melt.py :pre
+
+IMPORTANT NOTE: Any command must be executed by all MPI processes. However, evaluations and querying the system state is only available on rank 0.
+
+Feedback and Contributing :h2
+
+If you find this Python interface useful, please feel free to provide feedback
+and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also
+want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
+and maybe their latest research results. 

doc/src/tutorials.txt

@@ -7,6 +7,7 @@ Tutorials :h1
 
    tutorial_drude
    tutorial_github
+   tutorial_pylammps
    body
    manifolds
 

python/examples/pylammps/README

@@ -0,0 +1,28 @@
+# Compile LAMMPS as shared library
+
+git clone https://github.com/lammps/lammps.git
+cd lammps/src
+python Make.py -m mpi -png -s ffmpeg exceptions -a file
+
+make -j 4 mode=shlib auto
+cd ../..
+
+# Install Python package
+
+virtualenv testing
+source testing/bin/activate
+
+(testing) cd lammps/python
+(testing) python install.py
+(testing) pip install jupyter matplotlib mpi4py
+
+(testing) cd ../../examples
+
+# Launch jupter and work inside browser
+
+(testing) jupyter notebook
+
+# Use Ctrl+c to stop jupyter
+
+# finally exit the virtualenv
+(testing) deactivate

python/examples/pylammps/dihedrals/data.dihedral

@@ -0,0 +1,34 @@
+Comment line
+ 
+4 atoms
+0 bonds
+0 angles
+1 dihedrals
+0 impropers
+ 
+1 atom types
+0 bond types
+0 angle types
+1 dihedral types
+0 improper types
+ 
+-5.0   5.0      xlo xhi
+-5.0   5.0      ylo yhi
+-5.0   5.0      zlo zhi
+0.0   0.0   0.0   xy xz yz
+ 
+Atoms # molecular
+
+1      1   1     -1.00000     1.00000      0.00000
+2      1   1     -0.50000     0.00000      0.00000
+3      1   1      0.50000     0.00000      0.00000
+4      1   1      1.00000     1.00000      0.00000
+
+Dihedral Coeffs
+
+1      80.0   1   2
+
+Dihedrals
+
+1      1   1  2  3  4
+

python/examples/pylammps/mpi4py/hello.py

@@ -0,0 +1,4 @@
+from mpi4py import MPI
+
+comm=MPI.COMM_WORLD
+print("Hello from rank %d of %d" % (comm.rank, comm.size))

python/examples/pylammps/mpi4py/in.melt

@@ -0,0 +1,33 @@
+# 3d Lennard-Jones melt
+
+units		lj
+atom_style	atomic
+
+lattice		fcc 0.8442
+region		box block 0 10 0 10 0 10
+create_box	1 box
+create_atoms	1 box
+mass		1 1.0
+
+velocity	all create 3.0 87287
+
+pair_style	lj/cut 2.5
+pair_coeff	1 1 1.0 1.0 2.5
+
+neighbor	0.3 bin
+neigh_modify	every 20 delay 0 check no
+
+fix		1 all nve
+
+#dump		id all atom 50 dump.melt
+
+#dump		2 all image 25 image.*.jpg type type &
+#		axes yes 0.8 0.02 view 60 -30
+#dump_modify	2 pad 3
+
+#dump		3 all movie 25 movie.mpg type type &
+#		axes yes 0.8 0.02 view 60 -30
+#dump_modify	3 pad 3
+
+thermo		50
+run		250

python/examples/pylammps/mpi4py/melt.py

@@ -0,0 +1,10 @@
+from mpi4py import MPI
+from lammps import PyLammps
+
+L = PyLammps()
+L.file('in.melt')
+
+
+if MPI.COMM_WORLD.rank == 0:
+    pe = L.eval("pe")
+    print("Potential Energy:", pe)