From 69f813b22ec3d8b08035454980c2643f640fccdb Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 13 Feb 2018 16:41:23 +0100 Subject: [PATCH] fix up formatting of tutorials for PDF manual --- doc/Makefile | 2 +- doc/src/lammps.book | 1 + doc/src/lammps_tutorials.txt | 6 ++++ doc/src/tutorial_pylammps.txt | 52 +++++++++++++++++------------------ 4 files changed, 34 insertions(+), 27 deletions(-) create mode 100644 doc/src/lammps_tutorials.txt diff --git a/doc/Makefile b/doc/Makefile index b10b15d057..6e6f36a378 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -21,7 +21,7 @@ HAS_VIRTUALENV = YES endif 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) .PHONY: help clean-all clean epub html pdf old venv spelling anchor_check diff --git a/doc/src/lammps.book b/doc/src/lammps.book index 400018d248..878e4ad355 100644 --- a/doc/src/lammps.book +++ b/doc/src/lammps.book @@ -20,6 +20,7 @@ Section_python.html Section_errors.html Section_history.html +lammps_tutorials.html tutorial_bash_on_windows.html tutorial_drude.html tutorial_github.html diff --git a/doc/src/lammps_tutorials.txt b/doc/src/lammps_tutorials.txt new file mode 100644 index 0000000000..5ceda65b60 --- /dev/null +++ b/doc/src/lammps_tutorials.txt @@ -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. diff --git a/doc/src/tutorial_pylammps.txt b/doc/src/tutorial_pylammps.txt index 52eb6415db..11cddb3cbf 100644 --- a/doc/src/tutorial_pylammps.txt +++ b/doc/src/tutorial_pylammps.txt @@ -6,14 +6,14 @@ :line -PyLammps Tutorial :h1 +PyLammps Tutorial :h3 -Overview :h2 +Overview :h4 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 @@ -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 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 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 +lammps.PyLammps :h6 higher-level abstraction built on top of original C-Types interface manipulation of Python objects @@ -41,11 +41,11 @@ shorter, more concise Python 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 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 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 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 -Installation inside of a virtualenv :h3 +Installation inside of a virtualenv :h5 You can use virtualenv to create a custom Python environment specifically tuned 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 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 -Creating a virtualenv with lammps installed :h4 +Creating a virtualenv with lammps installed :h6 # create virtualenv name 'testing' :pre @@ -107,7 +107,7 @@ source testing/bin/activate :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 module. By using the default constructor, a new {lammps} instance is created. @@ -121,7 +121,7 @@ from lammps import lammps, PyLammps lmp = lammps() L = PyLammps(ptr=lmp) :pre -Commands :h2 +Commands :h4 Sending a LAMMPS command with the existing library interfaces is done using 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 -System state :h2 +System state :h4 In addition to dispatching commands directly through the PyLammps object, it 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 -Working with LAMMPS variables :h2 +Working with LAMMPS variables :h4 LAMMPS variables can be both defined and accessed via the PyLammps interface. @@ -229,7 +229,7 @@ property of this object. print(a.value) 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 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 -Accessing atom data :h2 +Accessing atom data :h4 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, @@ -263,7 +263,7 @@ 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 +Evaluating thermo data :h4 Each simulation run usually produces thermo output based on system state, 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 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 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 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 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 -IPyLammps Examples :h2 +IPyLammps Examples :h4 Examples of IPython notebooks can be found in the python/examples/pylammps 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 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 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) -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 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 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 @@ -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. -Feedback and Contributing :h2 +Feedback and Contributing :h4 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