forked from lijiext/lammps
Merge pull request #1762 from rbberger/doc_lammps_lexer
Add LAMMPSLexer for LAMMPS code-blocks in docs
This commit is contained in:
Axel Kohlmeyer
GitHub
commit
6d7a591dce
|
|
@ -17,7 +17,7 @@ one line at a time and each command takes effect when it is read.
|
|||
Thus this sequence of commands:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
timestep 0.5
|
||||
run 100
|
||||
|
|
@ -26,7 +26,7 @@ Thus this sequence of commands:
|
|||
does something different than this sequence:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
run 100
|
||||
timestep 0.5
|
||||
|
|
|
|||
|
|
@ -22,6 +22,10 @@ comment after a trailing "&" character will prevent the command from
|
|||
continuing on the next line. Also note that for multi-line commands a
|
||||
single leading "#" will comment out the entire command.
|
||||
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
# this is a comment
|
||||
|
||||
(3) The line is searched repeatedly for $ characters, which indicate
|
||||
variables that are replaced with a text string. See an exception in
|
||||
(6).
|
||||
|
|
@ -47,7 +51,7 @@ to use numeric formulas in an input script without having to assign
|
|||
them to variable names. For example, these 3 input script lines:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
variable X equal (xlo+xhi)/2+sqrt(v_area)
|
||||
region 1 block $X 2 INF INF EDGE EDGE
|
||||
|
|
@ -56,7 +60,7 @@ them to variable names. For example, these 3 input script lines:
|
|||
can be replaced by
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE
|
||||
|
||||
|
|
@ -72,7 +76,7 @@ specified a high-precision "%.20g" is used as the default.
|
|||
This can be useful for formatting print output to a desired precision:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"
|
||||
|
||||
|
|
@ -81,7 +85,7 @@ contain nested $ characters for other variables to substitute for.
|
|||
Thus you cannot do this:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
variable a equal 2
|
||||
variable b2 equal 4
|
||||
|
|
@ -113,7 +117,7 @@ can be enclosed in triple quotes, in which case "&" characters are not
|
|||
needed. For example:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
print "Volume = $v"
|
||||
print 'Volume = $v'
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ output support enabled.
|
|||
Step 1a: For the CMake based build system, the steps are:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir $LAMMPS_DIR/build-shared
|
||||
cd $LAMMPS_DIR/build-shared
|
||||
|
|
@ -69,7 +69,7 @@ Step 1a: For the CMake based build system, the steps are:
|
|||
Step 1b: For the legacy, make based build system, the steps are:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
cd $LAMMPS_DIR/src
|
||||
|
||||
|
|
@ -86,7 +86,7 @@ PyLammps is part of the lammps Python package. To install it simply install
|
|||
that package into your current Python installation with:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
make install-python
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ Benefits of using a virtualenv
|
|||
**Prerequisite (e.g. on Ubuntu)**
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
apt-get install python-virtualenv
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ Creating a virtualenv with lammps installed
|
|||
"""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
# create virtualenv named 'testing'
|
||||
virtualenv $HOME/python/testing
|
||||
|
|
@ -133,7 +133,7 @@ need to re-run CMake to update the location of the python executable
|
|||
to the location in the virtual environment with:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
cmake . -DPYTHON_EXECUTABLE=$(which python)
|
||||
|
||||
|
|
@ -155,7 +155,7 @@ 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.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
from lammps import PyLammps
|
||||
L = PyLammps()
|
||||
|
|
@ -163,7 +163,7 @@ module. By using the default constructor, a new *lammps* instance is created.
|
|||
You can also initialize PyLammps on top of this existing *lammps* object:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
from lammps import lammps, PyLammps
|
||||
lmp = lammps()
|
||||
|
|
@ -178,7 +178,7 @@ the command method of the lammps object instance.
|
|||
For instance, let's take the following LAMMPS command:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
region box block 0 10 0 5 -0.5 0.5
|
||||
|
||||
|
|
@ -186,7 +186,7 @@ In the original interface this command can be executed with the following
|
|||
Python code if *L* was a lammps instance:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.command("region box block 0 10 0 5 -0.5 0.5")
|
||||
|
||||
|
|
@ -194,7 +194,7 @@ With the PyLammps interface, any command can be split up into arbitrary parts
|
|||
separated by white-space, passed as individual arguments to a region method.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
|
||||
|
||||
|
|
@ -207,7 +207,7 @@ parameterization. In the original interface parameterization needed to be done
|
|||
manually by creating formatted strings.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
|
||||
|
||||
|
|
@ -215,7 +215,7 @@ In contrast, methods of PyLammps accept parameters directly and will convert
|
|||
them automatically to a final command string.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
|
||||
|
||||
|
|
@ -270,7 +270,7 @@ LAMMPS variables can be both defined and accessed via the PyLammps interface.
|
|||
To define a variable you can use the :doc:`variable <variable>` command:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.variable("a index 2")
|
||||
|
||||
|
|
@ -280,7 +280,7 @@ you can access an individual variable by retrieving a variable object from the
|
|||
L.variables dictionary by name
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
a = L.variables['a']
|
||||
|
||||
|
|
@ -288,7 +288,7 @@ The variable value can then be easily read and written by accessing the value
|
|||
property of this object.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
print(a.value)
|
||||
a.value = 4
|
||||
|
|
@ -301,7 +301,7 @@ passed string parameter can be any expression containing global thermo values,
|
|||
variables, compute or fix data.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
result = L.eval("ke") # kinetic energy
|
||||
result = L.eval("pe") # potential energy
|
||||
|
|
@ -316,7 +316,7 @@ Each element of this list is an object which exposes its properties (id, type,
|
|||
position, velocity, force, etc.).
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
# access first atom
|
||||
L.atoms[0].id
|
||||
|
|
@ -330,7 +330,7 @@ position, velocity, force, etc.).
|
|||
Some properties can also be used to set:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
# set position in 2D simulation
|
||||
L.atoms[0].position = (1.0, 0.0)
|
||||
|
|
@ -348,7 +348,7 @@ The first element is the output of the first run, the second element that of
|
|||
the second run.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.run(1000)
|
||||
L.runs[0] # data of first 1000 time steps
|
||||
|
|
@ -360,7 +360,7 @@ Each run contains a dictionary of all trajectories. Each trajectory is
|
|||
accessible through its thermo name:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
L.runs[0].step # list of time steps in first run
|
||||
L.runs[0].ke # list of kinetic energy values in first run
|
||||
|
|
@ -370,7 +370,7 @@ Together with matplotlib plotting data out of LAMMPS becomes simple:
|
|||
import matplotlib.plot as plt
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
steps = L.runs[0].step
|
||||
ke = L.runs[0].ke
|
||||
|
|
@ -408,7 +408,7 @@ To launch an instance of Jupyter simply run the following command inside your
|
|||
Python environment (this assumes you followed the Quick Start instructions):
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
jupyter notebook
|
||||
|
||||
|
|
@ -431,7 +431,7 @@ them using a datafile. Then one of the atoms is rotated along the central axis b
|
|||
setting its position from Python, which changes the dihedral angle.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
phi = [d \* math.pi / 180 for d in range(360)]
|
||||
|
||||
|
|
@ -465,7 +465,7 @@ Initially, a 2D system is created in a state with minimal energy.
|
|||
It is then disordered by moving each atom by a random delta.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
random.seed(27848)
|
||||
deltaperturb = 0.2
|
||||
|
|
@ -485,7 +485,7 @@ Finally, the Monte Carlo algorithm is implemented in Python. It continuously
|
|||
moves random atoms by a random delta and only accepts certain moves.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
estart = L.eval("pe")
|
||||
elast = estart
|
||||
|
|
@ -538,7 +538,7 @@ Using PyLammps and mpi4py (Experimental)
|
|||
PyLammps can be run in parallel using mpi4py. This python package can be installed using
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
pip install mpi4py
|
||||
|
||||
|
|
@ -546,7 +546,7 @@ The following is a short example which reads in an existing LAMMPS input file an
|
|||
executes it in parallel. You can find in.melt in the examples/melt folder.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: Python
|
||||
|
||||
from mpi4py import MPI
|
||||
from lammps import PyLammps
|
||||
|
|
@ -563,7 +563,7 @@ To run this script (melt.py) in parallel using 4 MPI processes we invoke the
|
|||
following mpirun command:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
mpirun -np 4 python melt.py
|
||||
|
||||
|
|
|
|||
|
|
@ -20,28 +20,20 @@ directories and files should be included.
|
|||
|
||||
If you downloaded LAMMPS from the public SVN or Git repositories, then
|
||||
the HTML and PDF files are not included. Instead you need to create
|
||||
them, in one of three ways:
|
||||
them, in one of two ways:
|
||||
|
||||
(a) You can "fetch" the current HTML and PDF files from the LAMMPS web
|
||||
site. Just type "make fetch". This should create a html\_www dir and
|
||||
Manual\_www.pdf/Developer\_www.pdf files. Note that if new LAMMPS
|
||||
features have been added more recently than the date of your version,
|
||||
the fetched documentation will include those changes (but your source
|
||||
code will not, unless you update your local repository).
|
||||
|
||||
(b) You can build the HTML and PDF files yourself, by typing "make
|
||||
html" followed by "make pdf". Note that the PDF make requires the
|
||||
HTML files already exist. This requires various tools including
|
||||
Sphinx, which the build process will attempt to download and install
|
||||
on your system, if not already available. See more details below.
|
||||
|
||||
(c) You can generate an older, simpler, less-fancy style of HTML
|
||||
documentation by typing "make old". This will create an "old"
|
||||
directory. This can be useful if (b) does not work on your box for
|
||||
some reason, or you want to quickly view the HTML version of a doc
|
||||
page you have created or edited yourself within the src directory.
|
||||
E.g. if you are planning to submit a new feature to LAMMPS.
|
||||
a. You can "fetch" the current HTML and PDF files from the LAMMPS web site.
|
||||
Just type "make fetch". This should create a html\_www dir and
|
||||
Manual\_www.pdf/Developer\_www.pdf files. Note that if new LAMMPS features
|
||||
have been added more recently than the date of your version, the fetched
|
||||
documentation will include those changes (but your source code will not, unless
|
||||
you update your local repository).
|
||||
|
||||
b. You can build the HTML and PDF files yourself, by typing "make
|
||||
html" followed by "make pdf". Note that the PDF make requires the
|
||||
HTML files already exist. This requires various tools including
|
||||
Sphinx, which the build process will attempt to download and install
|
||||
on your system, if not already available. See more details below.
|
||||
|
||||
----------
|
||||
|
||||
|
|
@ -50,14 +42,13 @@ The generation of all documentation is managed by the Makefile in
|
|||
the doc dir.
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
Documentation Build Options:
|
||||
|
||||
make html # generate HTML in html dir using Sphinx
|
||||
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
|
||||
# in doc dir via htmldoc and pdflatex
|
||||
make old # generate old-style HTML pages in old dir via txt2html
|
||||
make fetch # fetch HTML doc pages and 2 PDF files from web site
|
||||
# as a tarball and unpack into html dir and 2 PDFs
|
||||
make epub # generate LAMMPS.epub in ePUB format using Sphinx
|
||||
|
|
@ -82,7 +73,7 @@ Ubuntu
|
|||
------
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt-get install python-virtualenv
|
||||
|
||||
|
|
@ -90,7 +81,7 @@ Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version
|
|||
------------------------------------------------------------------------------------
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
sudo yum install python3-virtualenv
|
||||
|
||||
|
|
@ -98,7 +89,7 @@ Fedora (since version 22)
|
|||
-------------------------
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dnf install python3-virtualenv
|
||||
|
||||
|
|
@ -119,7 +110,7 @@ virtualenv
|
|||
Once Python 3 is installed, open a Terminal and type
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: bash
|
||||
|
||||
pip3 install virtualenv
|
||||
|
||||
|
|
@ -129,21 +120,6 @@ This will install virtualenv from the Python Package Index.
|
|||
----------
|
||||
|
||||
|
||||
Installing prerequisites for PDF build
|
||||
|
||||
Building the PDF manual requires a working C++ compiler (to
|
||||
compile the txt2html tool and a working installation of
|
||||
`HTMLDOC <https://www.msweet.org/htmldoc/>`_
|
||||
HTMLDOC has its own list of prerequisites, but in most cases
|
||||
you can install a binary package of it either through your
|
||||
Linux package manager or MacOS (dmg) and Windows installer
|
||||
(msi) packages from its
|
||||
`GitHub releases page at <https://github.com/michaelrsweet/htmldoc/releases>`_
|
||||
|
||||
|
||||
----------
|
||||
|
||||
|
||||
Installing prerequisites for epub build
|
||||
=======================================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,60 +0,0 @@
|
|||
"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS
|
||||
Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
LAMMPS input scripts :h3
|
||||
|
||||
LAMMPS executes by reading commands from a input script (text file),
|
||||
one line at a time. When the input script ends, LAMMPS exits. Each
|
||||
command causes LAMMPS to take some action. It may set an internal
|
||||
variable, read in a file, or run a simulation. Most commands have
|
||||
default settings, which means you only need to use the command if you
|
||||
wish to change the default.
|
||||
|
||||
In many cases, the ordering of commands in an input script is not
|
||||
important. However the following rules apply:
|
||||
|
||||
(1) LAMMPS does not read your entire input script and then perform a
|
||||
simulation with all the settings. Rather, the input script is read
|
||||
one line at a time and each command takes effect when it is read.
|
||||
Thus this sequence of commands:
|
||||
|
||||
timestep 0.5
|
||||
run 100
|
||||
run 100 :pre
|
||||
|
||||
does something different than this sequence:
|
||||
|
||||
run 100
|
||||
timestep 0.5
|
||||
run 100 :pre
|
||||
|
||||
In the first case, the specified timestep (0.5 fs) is used for two
|
||||
simulations of 100 timesteps each. In the 2nd case, the default
|
||||
timestep (1.0 fs) is used for the 1st 100 step simulation and a 0.5 fs
|
||||
timestep is used for the 2nd one.
|
||||
|
||||
(2) Some commands are only valid when they follow other commands. For
|
||||
example you cannot set the temperature of a group of atoms until atoms
|
||||
have been defined and a group command is used to define which atoms
|
||||
belong to the group.
|
||||
|
||||
(3) Sometimes command B will use values that can be set by command A.
|
||||
This means command A must precede command B in the input script if it
|
||||
is to have the desired effect. For example, the
|
||||
"read_data"_read_data.html command initializes the system by setting
|
||||
up the simulation box and assigning atoms to processors. If default
|
||||
values are not desired, the "processors"_processors.html and
|
||||
"boundary"_boundary.html commands need to be used before read_data to
|
||||
tell LAMMPS how to map processors to the simulation box.
|
||||
|
||||
Many input script errors are detected by LAMMPS and an ERROR or
|
||||
WARNING message is printed. The "Errors"_Errors.html doc page gives
|
||||
more information on what errors mean. The documentation for each
|
||||
command lists restrictions on how the command can be used.
|
||||
|
||||
|
|
@ -1,136 +0,0 @@
|
|||
"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS
|
||||
Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
Parsing rules for input scripts :h3
|
||||
|
||||
Each non-blank line in the input script is treated as a command.
|
||||
LAMMPS commands are case sensitive. Command names are lower-case, as
|
||||
are specified command arguments. Upper case letters may be used in
|
||||
file names or user-chosen ID strings.
|
||||
|
||||
Here are 6 rules for how each line in the input script is parsed by
|
||||
LAMMPS:
|
||||
|
||||
(1) If the last printable character on the line is a "&" character,
|
||||
the command is assumed to continue on the next line. The next line is
|
||||
concatenated to the previous line by removing the "&" character and
|
||||
line break. This allows long commands to be continued across two or
|
||||
more lines. See the discussion of triple quotes in (6) for how to
|
||||
continue a command across multiple line without using "&" characters.
|
||||
|
||||
(2) All characters from the first "#" character onward are treated as
|
||||
comment and discarded. See an exception in (6). Note that a
|
||||
comment after a trailing "&" character will prevent the command from
|
||||
continuing on the next line. Also note that for multi-line commands a
|
||||
single leading "#" will comment out the entire command.
|
||||
|
||||
(3) The line is searched repeatedly for $ characters, which indicate
|
||||
variables that are replaced with a text string. See an exception in
|
||||
(6).
|
||||
|
||||
If the $ is followed by curly brackets, then the variable name is the
|
||||
text inside the curly brackets. If no curly brackets follow the $,
|
||||
then the variable name is the single character immediately following
|
||||
the $. Thus $\{myTemp\} and $x refer to variable names "myTemp" and
|
||||
"x".
|
||||
|
||||
How the variable is converted to a text string depends on what style
|
||||
of variable it is; see the "variable"_variable.html doc page for details.
|
||||
It can be a variable that stores multiple text strings, and return one
|
||||
of them. The returned text string can be multiple "words" (space
|
||||
separated) which will then be interpreted as multiple arguments in the
|
||||
input command. The variable can also store a numeric formula which
|
||||
will be evaluated and its numeric result returned as a string.
|
||||
|
||||
As a special case, if the $ is followed by parenthesis, then the text
|
||||
inside the parenthesis is treated as an "immediate" variable and
|
||||
evaluated as an "equal-style variable"_variable.html. This is a way
|
||||
to use numeric formulas in an input script without having to assign
|
||||
them to variable names. For example, these 3 input script lines:
|
||||
|
||||
variable X equal (xlo+xhi)/2+sqrt(v_area)
|
||||
region 1 block $X 2 INF INF EDGE EDGE
|
||||
variable X delete :pre
|
||||
|
||||
can be replaced by
|
||||
|
||||
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE :pre
|
||||
|
||||
so that you do not have to define (or discard) a temporary variable X.
|
||||
|
||||
Additionally, the "immediate" variable expression may be followed by a
|
||||
colon, followed by a C-style format string, e.g. ":%f" or ":%.10g".
|
||||
The format string must be appropriate for a double-precision
|
||||
floating-point value. The format string is used to output the result
|
||||
of the variable expression evaluation. If a format string is not
|
||||
specified a high-precision "%.20g" is used as the default.
|
||||
|
||||
This can be useful for formatting print output to a desired precision:
|
||||
|
||||
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom" :pre
|
||||
|
||||
Note that neither the curly-bracket or immediate form of variables can
|
||||
contain nested $ characters for other variables to substitute for.
|
||||
Thus you cannot do this:
|
||||
|
||||
variable a equal 2
|
||||
variable b2 equal 4
|
||||
print "B2 = $\{b$a\}" :pre
|
||||
|
||||
Nor can you specify this $($x-1.0) for an immediate variable, but
|
||||
you could use $(v_x-1.0), since the latter is valid syntax for an
|
||||
"equal-style variable"_variable.html.
|
||||
|
||||
See the "variable"_variable.html command for more details of how
|
||||
strings are assigned to variables and evaluated, and how they can be
|
||||
used in input script commands.
|
||||
|
||||
(4) The line is broken into "words" separated by white-space (tabs,
|
||||
spaces). Note that words can thus contain letters, digits,
|
||||
underscores, or punctuation characters.
|
||||
|
||||
(5) The first word is the command name. All successive words in the
|
||||
line are arguments.
|
||||
|
||||
(6) If you want text with spaces to be treated as a single argument,
|
||||
it can be enclosed in either single or double or triple quotes. A
|
||||
long single argument enclosed in single or double quotes can span
|
||||
multiple lines if the "&" character is used, as described above. When
|
||||
the lines are concatenated together (and the "&" characters and line
|
||||
breaks removed), the text will become a single line. If you want
|
||||
multiple lines of an argument to retain their line breaks, the text
|
||||
can be enclosed in triple quotes, in which case "&" characters are not
|
||||
needed. For example:
|
||||
|
||||
print "Volume = $v"
|
||||
print 'Volume = $v'
|
||||
if "$\{steps\} > 1000" then quit
|
||||
variable a string "red green blue &
|
||||
purple orange cyan"
|
||||
print """
|
||||
System volume = $v
|
||||
System temperature = $t
|
||||
""" :pre
|
||||
|
||||
In each case, the single, double, or triple quotes are removed when
|
||||
the single argument they enclose is stored internally.
|
||||
|
||||
See the "dump modify format"_dump_modify.html, "print"_print.html,
|
||||
"if"_if.html, and "python"_python.html commands for examples.
|
||||
|
||||
A "#" or "$" character that is between quotes will not be treated as a
|
||||
comment indicator in (2) or substituted for as a variable in (3).
|
||||
|
||||
NOTE: If the argument is itself a command that requires a quoted
|
||||
argument (e.g. using a "print"_print.html command as part of an
|
||||
"if"_if.html or "run every"_run.html command), then single, double, or
|
||||
triple quotes can be nested in the usual manner. See the doc pages
|
||||
for those commands for examples. Only one of level of nesting is
|
||||
allowed, but that should be sufficient for most use cases.
|
||||
|
||||
|
|
@ -1,481 +0,0 @@
|
|||
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
PyLammps Tutorial :h3
|
||||
|
||||
<!-- RST
|
||||
.. contents::
|
||||
|
||||
END_RST -->
|
||||
|
||||
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 common LAMMPS functionality, in contrast to
|
||||
the lammps.py wrapper on the C-style LAMMPS library interface which is
|
||||
written using Python ctypes. The lammps.py wrapper is discussed on
|
||||
the "Python library"_Python_library.html doc page.
|
||||
|
||||
Unlike the flat ctypes interface, PyLammps 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 :h5
|
||||
|
||||
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 :h6
|
||||
|
||||
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 :h4
|
||||
|
||||
System-wide Installation :h5
|
||||
|
||||
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
|
||||
MOLECULE package and compile LAMMPS with C++ exceptions, PNG, JPEG and FFMPEG
|
||||
output support enabled.
|
||||
|
||||
Step 1a: For the CMake based build system, the steps are:
|
||||
|
||||
mkdir $LAMMPS_DIR/build-shared
|
||||
cd $LAMMPS_DIR/build-shared :pre
|
||||
|
||||
# MPI, PNG, Jpeg, FFMPEG are auto-detected
|
||||
cmake ../cmake -DPKG_MOLECULE=yes -DLAMMPS_EXCEPTIONS=yes -DBUILD_LIB=yes -DBUILD_SHARED_LIBS=yes
|
||||
make :pre
|
||||
|
||||
Step 1b: For the legacy, make based build system, the steps are:
|
||||
|
||||
cd $LAMMPS_DIR/src :pre
|
||||
|
||||
# add packages if necessary
|
||||
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 :h6
|
||||
|
||||
PyLammps is part of the lammps Python package. To install it simply install
|
||||
that package into your current Python installation with:
|
||||
|
||||
make install-python :pre
|
||||
|
||||
NOTE: Recompiling the shared library requires re-installing the Python package
|
||||
|
||||
|
||||
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 :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)
|
||||
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 :h6
|
||||
|
||||
# create virtualenv named 'testing'
|
||||
virtualenv $HOME/python/testing :pre
|
||||
|
||||
# activate 'testing' environment
|
||||
source $HOME/python/testing/bin/activate :pre
|
||||
|
||||
Now configure and compile the LAMMPS shared library as outlined above.
|
||||
When using CMake and the shared library has already been build, you
|
||||
need to re-run CMake to update the location of the python executable
|
||||
to the location in the virtual environment with:
|
||||
|
||||
cmake . -DPYTHON_EXECUTABLE=$(which python) :pre
|
||||
|
||||
# install LAMMPS package in virtualenv
|
||||
(testing) make install-python :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 :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.
|
||||
|
||||
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 :h4
|
||||
|
||||
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 white-space, 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 white-space.
|
||||
|
||||
The benefit of this approach is avoiding redundant command calls and easier
|
||||
parameterization. In the original interface parameterization 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 :h4
|
||||
|
||||
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 :h4
|
||||
|
||||
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 :h4
|
||||
|
||||
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 :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,
|
||||
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 :h4
|
||||
|
||||
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 :h4
|
||||
|
||||
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 :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
|
||||
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 :h4
|
||||
|
||||
Examples of IPython notebooks can be found in the python/examples/pylammps
|
||||
sub-directory. 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 exceptions, PNG, JPEG and FFMPEG support
|
||||
you should be able to rerun all of these notebooks.
|
||||
|
||||
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.
|
||||
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 :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.
|
||||
|
||||
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) :h4
|
||||
|
||||
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 :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
|
||||
want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
|
||||
and maybe their latest research results.
|
||||
|
|
@ -1,133 +0,0 @@
|
|||
"Previous Section"_Errors.html - "LAMMPS WWW Site"_lws -
|
||||
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
|
||||
Section"_Manual.html :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
Building the LAMMPS manual :h2
|
||||
|
||||
Depending on how you obtained LAMMPS, the doc directory has 2 or 3
|
||||
sub-directories and optionally 2 PDF files and 2 e-book format files:
|
||||
|
||||
src # content files for LAMMPS documentation
|
||||
html # HTML version of the LAMMPS manual (see html/Manual.html)
|
||||
tools # tools and settings for building the documentation
|
||||
Manual.pdf # large PDF version of entire manual
|
||||
Developer.pdf # small PDF with info about how LAMMPS is structured
|
||||
LAMMPS.epub # Manual in ePUB e-book format
|
||||
LAMMPS.mobi # Manual in MOBI e-book format :pre
|
||||
|
||||
If you downloaded LAMMPS as a tarball from the web site, all these
|
||||
directories and files should be included.
|
||||
|
||||
If you downloaded LAMMPS from the public SVN or Git repositories, then
|
||||
the HTML and PDF files are not included. Instead you need to create
|
||||
them, in one of three ways:
|
||||
|
||||
(a) You can "fetch" the current HTML and PDF files from the LAMMPS web
|
||||
site. Just type "make fetch". This should create a html_www dir and
|
||||
Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS
|
||||
features have been added more recently than the date of your version,
|
||||
the fetched documentation will include those changes (but your source
|
||||
code will not, unless you update your local repository).
|
||||
|
||||
(b) You can build the HTML and PDF files yourself, by typing "make
|
||||
html" followed by "make pdf". Note that the PDF make requires the
|
||||
HTML files already exist. This requires various tools including
|
||||
Sphinx, which the build process will attempt to download and install
|
||||
on your system, if not already available. See more details below.
|
||||
|
||||
(c) You can generate an older, simpler, less-fancy style of HTML
|
||||
documentation by typing "make old". This will create an "old"
|
||||
directory. This can be useful if (b) does not work on your box for
|
||||
some reason, or you want to quickly view the HTML version of a doc
|
||||
page you have created or edited yourself within the src directory.
|
||||
E.g. if you are planning to submit a new feature to LAMMPS.
|
||||
|
||||
:line
|
||||
|
||||
The generation of all documentation is managed by the Makefile in
|
||||
the doc dir.
|
||||
|
||||
Documentation Build Options: :pre
|
||||
|
||||
make html # generate HTML in html dir using Sphinx
|
||||
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
|
||||
# in doc dir via htmldoc and pdflatex
|
||||
make old # generate old-style HTML pages in old dir via txt2html
|
||||
make fetch # fetch HTML doc pages and 2 PDF files from web site
|
||||
# as a tarball and unpack into html dir and 2 PDFs
|
||||
make epub # generate LAMMPS.epub in ePUB format using Sphinx
|
||||
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
|
||||
make clean # remove intermediate RST files created by HTML build
|
||||
make clean-all # remove entire build folder and any cached data :pre
|
||||
make anchor_check # check for duplicate anchor labels
|
||||
make spelling # spell-check the manual
|
||||
|
||||
:line
|
||||
|
||||
Installing prerequisites for HTML build :h3
|
||||
|
||||
To run the HTML documentation build toolchain, Python 3 and virtualenv
|
||||
have to be installed. Here are instructions for common setups:
|
||||
|
||||
Ubuntu :h4
|
||||
|
||||
sudo apt-get install python-virtualenv :pre
|
||||
|
||||
Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x) :h4
|
||||
|
||||
sudo yum install python3-virtualenv :pre
|
||||
|
||||
Fedora (since version 22) :h4
|
||||
|
||||
sudo dnf install python3-virtualenv :pre
|
||||
|
||||
MacOS X :h4
|
||||
|
||||
Python 3 :h5
|
||||
|
||||
Download the latest Python 3 MacOS X package from
|
||||
"https://www.python.org"_https://www.python.org
|
||||
and install it. This will install both Python 3
|
||||
and pip3.
|
||||
|
||||
virtualenv :h5
|
||||
|
||||
Once Python 3 is installed, open a Terminal and type
|
||||
|
||||
pip3 install virtualenv :pre
|
||||
|
||||
This will install virtualenv from the Python Package Index.
|
||||
|
||||
:line
|
||||
|
||||
Installing prerequisites for PDF build
|
||||
|
||||
Building the PDF manual requires a working C++ compiler (to
|
||||
compile the txt2html tool and a working installation of
|
||||
"HTMLDOC"_https://www.msweet.org/htmldoc/
|
||||
HTMLDOC has its own list of prerequisites, but in most cases
|
||||
you can install a binary package of it either through your
|
||||
Linux package manager or MacOS (dmg) and Windows installer
|
||||
(msi) packages from its
|
||||
"GitHub releases page at"_https://github.com/michaelrsweet/htmldoc/releases
|
||||
|
||||
:line
|
||||
|
||||
Installing prerequisites for epub build :h3
|
||||
|
||||
ePUB :h4
|
||||
|
||||
Same as for HTML. This uses the same tools and configuration
|
||||
files as the HTML tree.
|
||||
|
||||
For converting the generated ePUB file to a MOBI format file
|
||||
(for e-book readers like Kindle, that cannot read ePUB), you
|
||||
also need to have the 'ebook-convert' tool from the "calibre"
|
||||
software installed. "http://calibre-ebook.com/"_http://calibre-ebook.com/
|
||||
You first create the ePUB file and then convert it with 'make mobi'
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
from pygments.lexer import RegexLexer, words
|
||||
from pygments.token import *
|
||||
|
||||
LAMMPS_COMMANDS = ("angle_coeff", "angle_style", "atom_modify", "atom_style",
|
||||
"balance", "bond_coeff", "bond_style", "bond_write", "boundary", "box",
|
||||
"change_box", "clear", "comm_modify", "comm_style", "compute",
|
||||
"compute_modify", "create_atoms", "create_bonds", "create_box", "delete_atoms",
|
||||
"delete_bonds", "dielectric", "dihedral_coeff", "dihedral_style", "dimension",
|
||||
"displace_atoms", "dump", "dump_modify", "dynamical_matrix", "echo", "fix",
|
||||
"fix_modify", "group", "group2ndx", "hyper", "if", "improper_coeff",
|
||||
"improper_style", "include", "info", "jump", "kim_init", "kim_interactions",
|
||||
"kim_param", "kim_query", "kspace_modify", "kspace_style", "label", "lattice",
|
||||
"log", "mass", "message", "minimize", "min_modify", "min_style", "molecule",
|
||||
"ndx2group", "neb", "neb/spin", "neighbor", "neigh_modify", "newton", "next",
|
||||
"package", "pair_coeff", "pair_modify", "pair_style", "pair_write",
|
||||
"partition", "prd", "print", "processors", "python", "quit", "read_data",
|
||||
"read_dump", "read_restart", "region", "replicate", "rerun", "reset_ids",
|
||||
"reset_timestep", "restart", "run", "run_style", "server", "set", "shell",
|
||||
"special_bonds", "suffix", "tad", "temper", "temper/grem", "temper/npt",
|
||||
"thermo", "thermo_modify", "thermo_style", "then", "third_order", "timer", "timestep",
|
||||
"uncompute", "undump", "unfix", "units", "variable", "velocity", "write_coeff",
|
||||
"write_data", "write_dump", "write_restart")
|
||||
|
||||
class LAMMPSLexer(RegexLexer):
|
||||
name = 'LAMMPS'
|
||||
tokens = {
|
||||
'root': [
|
||||
(words(LAMMPS_COMMANDS, suffix=r'\b', prefix=r'^'), Keyword),
|
||||
(r'#.*?\n', Comment),
|
||||
('"', String, 'string'),
|
||||
('\'', String, 'single_quote_string'),
|
||||
(r'[0-9]+(\.[0-9]+)?([eE]\-?[0-9]+)?', Number),
|
||||
('\$?\(', Name.Variable, 'expression'),
|
||||
('\$\{', Name.Variable, 'variable'),
|
||||
(r'[\w_\.\[\]]+', Name),
|
||||
(r'\$[\w_]+', Name.Variable),
|
||||
(r'\s+', Whitespace),
|
||||
(r'[\+\-\*\/&=<>]', Operator),
|
||||
],
|
||||
'variable' : [
|
||||
('[^\}]+', Name.Variable),
|
||||
('\}', Name.Variable, '#pop'),
|
||||
],
|
||||
'string' : [
|
||||
('[^"]+', String),
|
||||
('"', String, '#pop'),
|
||||
],
|
||||
'single_quote_string' : [
|
||||
('[^\']+', String),
|
||||
('\'', String, '#pop'),
|
||||
],
|
||||
'expression' : [
|
||||
('[^\(\)]+', Name.Variable),
|
||||
('\(', Name.Variable, 'expression'),
|
||||
('\)', Name.Variable, '#pop'),
|
||||
]
|
||||
}
|
||||
|
|
@ -317,3 +317,9 @@ if spelling_spec:
|
|||
|
||||
spelling_lang='en_US'
|
||||
spelling_word_list_filename='false_positives.txt'
|
||||
|
||||
sys.path.append(os.path.join(os.path.dirname(__file__), '.'))
|
||||
import LAMMPSLexer
|
||||
from sphinx.highlighting import lexers
|
||||
|
||||
lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True)
|
||||
|
|
|
|||
Loading…
Reference in New Issue