jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix up formatting of tutorials for PDF manual

This commit is contained in:
Axel Kohlmeyer 2018-02-13 16:41:23 +01:00
parent b3693f891b
commit 69f813b22e
4 changed files with 34 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Makefile
View File

@ -21,7 +21,7 @@ HAS_VIRTUALENV = YES
endif endif
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
SOURCES=$(filter-out src/lammps_commands.txt,$(wildcard src/*.txt)) SOURCES=$(filter-out src/lammps_commands.txt src/lammps_tutorials.txt,$(wildcard src/*.txt))
OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst) OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst)
.PHONY: help clean-all clean epub html pdf old venv spelling anchor_check .PHONY: help clean-all clean epub html pdf old venv spelling anchor_check

1
doc/src/lammps.book
View File

@ -20,6 +20,7 @@ Section_python.html
Section_errors.html Section_errors.html
Section_history.html Section_history.html
lammps_tutorials.html
tutorial_bash_on_windows.html tutorial_bash_on_windows.html
tutorial_drude.html tutorial_drude.html
tutorial_github.html tutorial_github.html

6
doc/src/lammps_tutorials.txt Normal file
View File

@ -0,0 +1,6 @@
Tutorials :h2
The following pages contain some in-depth tutorials for
selected topics, that did not fit into any other place
in the manual.

52
doc/src/tutorial_pylammps.txt
View File

@ -6,14 +6,14 @@
:line :line
PyLammps Tutorial :h1 PyLammps Tutorial :h3
<!-- RST <!-- RST
.. contents:: .. contents::
END_RST --> END_RST -->
Overview :h2 Overview :h4
PyLammps is a Python wrapper class which can be created on its own or use an 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 existing lammps Python object. It creates a simpler, Python-like interface to
@ -23,16 +23,16 @@ C++ code implementation. Finally, the IPyLammps wrapper builds on top of
PyLammps and adds some additional features for IPython integration into IPython PyLammps and adds some additional features for IPython integration into IPython
notebooks, e.g. for embedded visualization output from dump/image. notebooks, e.g. for embedded visualization output from dump/image.
Comparison of lammps and PyLammps interfaces :h3 Comparison of lammps and PyLammps interfaces :h5
lammps.lammps :h4 lammps.lammps :h6
uses C-Types uses C-Types
direct memory access to native C++ data direct memory access to native C++ data
provides functions to send and receive data to LAMMPS provides functions to send and receive data to LAMMPS
requires knowledge of how LAMMPS internally works (C pointers, etc) :ul requires knowledge of how LAMMPS internally works (C pointers, etc) :ul
lammps.PyLammps :h4 lammps.PyLammps :h6
higher-level abstraction built on top of original C-Types interface higher-level abstraction built on top of original C-Types interface
manipulation of Python objects manipulation of Python objects
@ -41,11 +41,11 @@ shorter, more concise Python
better IPython integration, designed for quick prototyping :ul better IPython integration, designed for quick prototyping :ul
Quick Start :h2 Quick Start :h4
System-wide Installation :h3 System-wide Installation :h5
Step 1: Building LAMMPS as a shared library :h4 Step 1: Building LAMMPS as a shared library :h6
To use LAMMPS inside of Python it has to be compiled as shared library. This 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 enable the library is then loaded by the Python interface. In this example we enable the
@ -60,7 +60,7 @@ make yes-MOLECULE :pre
# compile shared library using Makefile # compile shared library using Makefile
make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG -DLAMMPS_EXCEPTIONS" JPG_LIB="-lpng -ljpeg" :pre make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG -DLAMMPS_EXCEPTIONS" JPG_LIB="-lpng -ljpeg" :pre
Step 2: Installing the LAMMPS Python package :h4 Step 2: Installing the LAMMPS Python package :h6
PyLammps is part of the lammps Python package. To install it simply install PyLammps is part of the lammps Python package. To install it simply install
that package into your current Python installation. that package into your current Python installation.
@ -71,12 +71,12 @@ python install.py :pre
NOTE: Recompiling the shared library requires reinstalling the Python package NOTE: Recompiling the shared library requires reinstalling the Python package
Installation inside of a virtualenv :h3 Installation inside of a virtualenv :h5
You can use virtualenv to create a custom Python environment specifically tuned You can use virtualenv to create a custom Python environment specifically tuned
for your workflow. for your workflow.
Benefits of using a virtualenv :h4 Benefits of using a virtualenv :h6
isolation of your system Python installation from your development installation isolation of your system Python installation from your development installation
installation can happen in your user directory without root access (useful for HPC clusters) installation can happen in your user directory without root access (useful for HPC clusters)
@ -87,7 +87,7 @@ you can even install specific old versions of a package if necessary :ul
apt-get install python-virtualenv :pre apt-get install python-virtualenv :pre
Creating a virtualenv with lammps installed :h4 Creating a virtualenv with lammps installed :h6
# create virtualenv name 'testing' :pre # create virtualenv name 'testing' :pre
@ -107,7 +107,7 @@ source testing/bin/activate :pre
(testing) deactivate :pre (testing) deactivate :pre
Creating a new instance of PyLammps :h2 Creating a new instance of PyLammps :h4
To create a PyLammps object you need to first import the class from the lammps 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. module. By using the default constructor, a new {lammps} instance is created.
@ -121,7 +121,7 @@ from lammps import lammps, PyLammps
lmp = lammps() lmp = lammps()
L = PyLammps(ptr=lmp) :pre L = PyLammps(ptr=lmp) :pre
Commands :h2 Commands :h4
Sending a LAMMPS command with the existing library interfaces is done using Sending a LAMMPS command with the existing library interfaces is done using
the command method of the lammps object instance. the command method of the lammps object instance.
@ -155,7 +155,7 @@ them automatically to a final command string.
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) :pre L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) :pre
System state :h2 System state :h4
In addition to dispatching commands directly through the PyLammps object, it In addition to dispatching commands directly through the PyLammps object, it
also provides several properties which allow you to query the system state. also provides several properties which allow you to query the system state.
@ -208,7 +208,7 @@ List of groups present in the current system :dd
:dle :dle
Working with LAMMPS variables :h2 Working with LAMMPS variables :h4
LAMMPS variables can be both defined and accessed via the PyLammps interface. LAMMPS variables can be both defined and accessed via the PyLammps interface.
@ -229,7 +229,7 @@ property of this object.
print(a.value) print(a.value)
a.value = 4 :pre a.value = 4 :pre
Retrieving the value of an arbitrary LAMMPS expressions :h2 Retrieving the value of an arbitrary LAMMPS expressions :h4
LAMMPS expressions can be immediately evaluated by using the eval method. The LAMMPS expressions can be immediately evaluated by using the eval method. The
passed string parameter can be any expression containing global thermo values, passed string parameter can be any expression containing global thermo values,
@ -240,7 +240,7 @@ result = L.eval("pe") # potential energy :pre
result = L.eval("v_t/2.0") :pre result = L.eval("v_t/2.0") :pre
Accessing atom data :h2 Accessing atom data :h4
All atoms in the current simulation can be accessed by using the L.atoms list. 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, Each element of this list is an object which exposes its properties (id, type,
@ -263,7 +263,7 @@ L.atoms\[0\].position = (1.0, 0.0) :pre
# set position in 3D simulation # set position in 3D simulation
L.atoms\[0\].position = (1.0, 0.0, 1.) :pre L.atoms\[0\].position = (1.0, 0.0, 1.) :pre
Evaluating thermo data :h2 Evaluating thermo data :h4
Each simulation run usually produces thermo output based on system state, Each simulation run usually produces thermo output based on system state,
computes, fixes or variables. The trajectories of these values can be queried computes, fixes or variables. The trajectories of these values can be queried
@ -291,7 +291,7 @@ steps = L.runs\[0\].step
ke = L.runs\[0\].ke ke = L.runs\[0\].ke
plt.plot(steps, ke) :pre plt.plot(steps, ke) :pre
Error handling with PyLammps :h2 Error handling with PyLammps :h4
Compiling the shared library with C++ exception support provides a better error Compiling the shared library with C++ exception support provides a better error
handling experience. Without exceptions the LAMMPS code will terminate the handling experience. Without exceptions the LAMMPS code will terminate the
@ -304,7 +304,7 @@ 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 advised to save your data and terminate the Python instance as quickly as
possible. possible.
Using PyLammps in IPython notebooks and Jupyter :h2 Using PyLammps in IPython notebooks and Jupyter :h4
If the LAMMPS Python package is installed for the same Python interpreter as 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 IPython, you can use PyLammps directly inside of an IPython notebook inside of
@ -320,7 +320,7 @@ Python environment (this assumes you followed the Quick Start instructions):
jupyter notebook :pre jupyter notebook :pre
IPyLammps Examples :h2 IPyLammps Examples :h4
Examples of IPython notebooks can be found in the python/examples/pylammps Examples of IPython notebooks can be found in the python/examples/pylammps
subdirectory. To open these notebooks launch {jupyter notebook} inside this subdirectory. To open these notebooks launch {jupyter notebook} inside this
@ -328,7 +328,7 @@ directory and navigate to one of them. If you compiled and installed
a LAMMPS shared library with exceptions, PNG, JPEG and FFMPEG support a LAMMPS shared library with exceptions, PNG, JPEG and FFMPEG support
you should be able to rerun all of these notebooks. you should be able to rerun all of these notebooks.
Validating a dihedral potential :h3 Validating a dihedral potential :h5
This example showcases how an IPython Notebook can be used to compare a simple 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. LAMMPS simulation of a harmonic dihedral potential to its analytical solution.
@ -353,7 +353,7 @@ plot inside the IPython notebook.
:c,image(JPG/pylammps_dihedral.jpg) :c,image(JPG/pylammps_dihedral.jpg)
Running a Monte Carlo relaxation :h3 Running a Monte Carlo relaxation :h5
This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation 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. simulation, computing and plotting energy terms and even embedding video output.
@ -424,7 +424,7 @@ The energies of each iteration are collected in a Python list and finally plotte
The IPython notebook also shows how to use dump commands and embed video files The IPython notebook also shows how to use dump commands and embed video files
inside of the IPython notebook. inside of the IPython notebook.
Using PyLammps and mpi4py (Experimental) :h2 Using PyLammps and mpi4py (Experimental) :h4
PyLammps can be run in parallel using mpi4py. This python package can be installed using PyLammps can be run in parallel using mpi4py. This python package can be installed using
@ -451,7 +451,7 @@ 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. 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 Feedback and Contributing :h4
If you find this Python interface useful, please feel free to provide feedback 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 and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also