diff --git a/doc/Section_start.html b/doc/Section_start.html
index d157bf079..a83aaa0ad 100644
--- a/doc/Section_start.html
+++ b/doc/Section_start.html
@@ -1,1142 +1,1174 @@
<HTML>
<CENTER><A HREF = "Section_intro.html">Previous Section</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> - <A HREF = "Section_commands.html">Next Section</A>
</CENTER>
<HR>
<H3>2. Getting Started
</H3>
<P>This section describes how to build and run LAMMPS, for both new and
experienced users.
</P>
2.1 <A HREF = "#2_1">What's in the LAMMPS distribution</A><BR>
2.2 <A HREF = "#2_2">Making LAMMPS</A><BR>
2.3 <A HREF = "#2_3">Making LAMMPS with optional packages</A><BR>
2.4 <A HREF = "#2_4">Building LAMMPS as a library</A><BR>
2.5 <A HREF = "#2_5">Running LAMMPS</A><BR>
2.6 <A HREF = "#2_6">Command-line options</A><BR>
2.7 <A HREF = "#2_7">Screen output</A><BR>
2.8 <A HREF = "#2_8">Running on GPUs</A><BR>
2.9 <A HREF = "#2_9">Tips for users of previous versions</A> <BR>
<HR>
<H4><A NAME = "2_1"></A>2.1 What's in the LAMMPS distribution
</H4>
<P>When you download LAMMPS you will need to unzip and untar the
downloaded file with the following commands, after placing the file in
an appropriate directory.
</P>
<PRE>gunzip lammps*.tar.gz
tar xvf lammps*.tar
</PRE>
<P>This will create a LAMMPS directory containing two files and several
sub-directories:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >README</TD><TD > text file</TD></TR>
<TR><TD >LICENSE</TD><TD > the GNU General Public License (GPL)</TD></TR>
<TR><TD >bench</TD><TD > benchmark problems</TD></TR>
<TR><TD >couple</TD><TD > code coupling examples, using LAMMPS as a library</TD></TR>
<TR><TD >doc</TD><TD > documentation</TD></TR>
<TR><TD >examples</TD><TD > simple test problems</TD></TR>
<TR><TD >potentials</TD><TD > embedded atom method (EAM) potential files</TD></TR>
<TR><TD >src</TD><TD > source files</TD></TR>
<TR><TD >tools</TD><TD > pre- and post-processing tools
</TD></TR></TABLE></DIV>
<P>If you download the Windows executable from the download page,
then you just get a single file:
</P>
<PRE>lmp_windows.exe
</PRE>
<P>Skip to the <A HREF = "#2_5">Running LAMMPS</A> section, to learn how to launch this
executable on a Windows box.
</P>
<P>The Windows executable also only includes certain packages and
bug-fixes/upgrades listed on <A HREF = "http://lammps.sandia.gov/bug.html">this
page</A> up to a certain date, as
stated on the download page. If you want something with more packages
or that is more current, you'll have to download the source tarball
and build it yourself, as described in the next section.
</P>
<HR>
<H4><A NAME = "2_2"></A>2.2 Making LAMMPS
</H4>
<P>This section has the following sub-sections:
</P>
<UL><LI><A HREF = "#2_2_1">Read this first</A>
<LI><A HREF = "#2_2_2">Building a LAMMPS executable</A>
<LI><A HREF = "#2_2_3">Common errors that can occur when making LAMMPS</A>
<LI><A HREF = "#2_2_4">Editing a new low-level Makefile</A>
<LI><A HREF = "#2_2_5">Additional build tips</A>
</UL>
<HR>
<A NAME = "2_2_1"></A><B><I>Read this first:</I></B>
<P>Building LAMMPS can be non-trivial. You will likely need to edit a
makefile, there are compiler options, additional libraries can be used
-(MPI, FFT), etc. Please read this section carefully. If you are not
-comfortable with makefiles, or building codes on a Unix platform, or
-running an MPI job on your machine, please find a local expert to help
-you. Many compiling, linking, and run problems that users are not
-really LAMMPS issues - they are peculiar to the user's system,
-compilers, libraries, etc. Such questions are better answered by a
-local expert.
+(MPI, FFT, JPEG), etc. Please read this section carefully. If you
+are not comfortable with makefiles, or building codes on a Unix
+platform, or running an MPI job on your machine, please find a local
+expert to help you. Many compiling, linking, and run problems that
+users are not really LAMMPS issues - they are peculiar to the user's
+system, compilers, libraries, etc. Such questions are better answered
+by a local expert.
</P>
<P>If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
please send an email to the
<A HREF = "http://lammps.sandia.gov/authors.html">developers</A>.
</P>
<P>If you succeed in building LAMMPS on a new kind of machine, for which
there isn't a similar Makefile for in the src/MAKE directory, send it
to the developers and we'll include it in future LAMMPS releases.
</P>
<HR>
<A NAME = "2_2_2"></A><B><I>Building a LAMMPS executable:</I></B>
<P>The src directory contains the C++ source and header files for LAMMPS.
It also contains a top-level Makefile and a MAKE sub-directory with
low-level Makefile.* files for several machines. From within the src
directory, type "make" or "gmake". You should see a list of available
choices. If one of those is the machine and options you want, you can
type a command like:
</P>
<PRE>make linux
gmake mac
</PRE>
<P>Note that on a multi-processor or multi-core platform you can launch a
parallel make, by using the "-j" switch with the make command, which
will build LAMMPS more quickly.
</P>
<P>If you get no errors and an executable like lmp_linux or lmp_mac is
produced, you're done; it's your lucky day.
</P>
<HR>
<A NAME = "2_2_3"></A><B><I>Common errors that can occur when making LAMMPS:</I></B>
<P>(1) If the make command breaks immediately with errors that indicate
it can't find files with a "*" in their names, this can be because
your machine's make doesn't support wildcard expansion in a makefile.
Try gmake instead of make. If that doesn't work, try using a -f
switch with your make command to use Makefile.list which explicitly
lists all the needed files, e.g.
</P>
<PRE>make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac
</PRE>
<P>The first "make" command will create a current Makefile.list with all
the file names in your src dir. The 2nd "make" command (make or
gmake) will use it to build LAMMPS.
</P>
<P>(2) Other errors typically occur because the low-level Makefile isn't
setup correctly for your machine. If your platform is named "foo",
you will need to create a Makefile.foo in the MAKE sub-directory. Use
whatever existing file is closest to your platform as a starting
point. See the next section for more instructions.
</P>
<P>(3) If you get a link-time error about missing libraries or missing
dependencies, then it can be because:
</P>
<UL><LI>you are including a package that needs an extra library, but have not pre-built the necessary <A HREF = "#2_3_3">package library</A>
<LI>you are linking to a library that doesn't exist on your system
<LI>you are not linking to the necessary system library
</UL>
<P>The first issue is discussed below. The other two issue mean you need
to edit your low-level Makefile.foo, as discussed in the next
sub-section.
</P>
<HR>
<A NAME = "2_2_4"></A><B><I>Editing a new low-level Makefile.foo:</I></B>
<P>These are the issues you need to address when editing a low-level
Makefile for your machine. The portions of the file you typically
need to edit are the first line, the "compiler/linker settings"
section, and the "system-specific settings" section.
</P>
<P>(1) Change the first line of Makefile.foo to list the word "foo" after
the "#", and whatever other options you set. This is the line you
will see if you just type "make".
</P>
<P>(3) The "compiler/linker settings" section lists compiler and linker
settings for your C++ compiler, including optimization flags. You can
use g++, the open-source GNU compiler, which is available on all Unix
systems. You can also use mpicc which will typically be available if
MPI is installed on your system, though you should check which actual
compiler it wraps. Vendor compilers often produce faster code. On
boxes with Intel CPUs, we suggest using the free Intel icc compiler,
which you can download from <A HREF = "http://www.intel.com/software/products/noncom">Intel's compiler site</A>.
</P>
<P>If building a C++ code on your machine requires additional libraries,
then you should list them as part of the LIB variable.
</P>
<P>The DEPFLAGS setting is what triggers the C++ compiler to create a
dependency list for a source file. This speeds re-compilation when
source (*.cpp) or header (*.h) files are edited. Some compilers do
not support dependency file creation, or may use a different switch
than -D. GNU g++ works with -D. If your compiler can't create
dependency files (a long list of errors involving *.d files), then
you'll need to create a Makefile.foo patterned after Makefile.storm,
which uses different rules that do not involve dependency files.
</P>
<P>(3) The "system-specific settings" section has 4 parts.
</P>
<P>(3.a) The LMP_INC variable is used to include options that turn on
-system-dependent ifdefs within the LAMMPS code.
-</P>
+system-dependent ifdefs within the LAMMPS code. The settings
+that are currently recogized are:
+</P>
+<UL><LI>-DLAMMPS_GZIP
+<LI>-DPACK_ARRAY
+<LI>-DPACK_POINTER
+<LI>-DPACK_MEMCPY
+<LI>-DLAMMPS_XDR
+<LI>-DLAMMPS_JPEG
+</UL>
<P>The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It requires that your Unix support the
-"popen" command. Using one of the -DPACK_ARRAY, -DPACK_POINTER, and
--DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM
-solver) on some platforms. The -DPACK_ARRAY setting is the default.
-If you use -DLAMMPS_XDR, the build will include XDR compatibility
+"popen" command.
+</P>
+<P>Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
+options can make for faster parallel FFTs (in the PPPM solver) on some
+platforms. The -DPACK_ARRAY setting is the default. See the
+<A HREF = "kspace_style.html">kspace_style</A> command for info about PPPM. See
+section (3.c) below for info about building LAMMPS with an FFT
+library.
+</P>
+<P>If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the <A HREF = "dump.html">dump</A> command for details.
</P>
+<P>If you use -DLAMMPS_JPEG, the <A HREF = "dump.html">dump image</A> command will be
+able to write out JPEG image files. If not, it will only be able to
+write out PPM image files. For JPEG files, you must also link LAMMPS
+with a JPEG library. See section (3.d) below for more details on
+this.
+</P>
<P>(3.b) The 3 MPI variables are used to specify an MPI library to build
LAMMPS with.
</P>
<P>If you want LAMMPS to run in parallel, you must have an MPI library
installed on your platform. If you use an MPI-wrapped compiler, such
as "mpicc" to build LAMMPS, you can probably leave these 3 variables
blank. If you do not use "mpicc" as your compiler/linker, then you
need to specify where the mpi.h file (MPI_INC) and the MPI library
(MPI_PATH) is found and its name (MPI_LIB).
</P>
<P>If you are installing MPI yourself, we recommend Argonne's MPICH 1.2
-or 2.0 which can be downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
-site</A>. LAM MPI should also work. If
+or 2.0 or OpenMPI. MPICH can be downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
+site</A>. OpenMPI can be downloaded the
+<A HREF = "http://www.open-mpi.org">OpenMPI site</A>. LAM MPI should also work. If
you are running on a big parallel platform, your system people or the
vendor should have already installed a version of MPI, which will be
-faster than MPICH or LAM, so find out how to build and link with it.
-If you use MPICH or LAM, you will have to configure and build it for
-your platform. The MPI configure script should have compiler options
-to enable you to use the same compiler you are using for the LAMMPS
-build, which can avoid problems that can arise when linking LAMMPS to
-the MPI library.
+faster than MPICH or OpenMPI or LAM, so find out how to build and link
+with it. If you use MPICH or OpenMPI or LAM, you will have to
+configure and build it for your platform. The MPI configure script
+should have compiler options to enable you to use the same compiler
+you are using for the LAMMPS build, which can avoid problems that can
+arise when linking LAMMPS to the MPI library.
</P>
<P>If you just want LAMMPS to run on a single processor, you can use the
-STUBS library in place of MPI, since you don't need an MPI library
+STUBS library in place of MPI, since you don't need a true MPI library
installed on your system. See the Makefile.serial file for how to
specify the 3 MPI variables. You will also need to build the STUBS
library for your platform before making LAMMPS itself. From the STUBS
dir, type "make" and it will hopefully create a libmpi.a suitable for
linking to LAMMPS. If this build fails, you will need to edit the
STUBS/Makefile for your platform.
</P>
<P>The file STUBS/mpi.cpp has a CPU timer function MPI_Wtime() that calls
gettimeofday() . If your system doesn't support gettimeofday() ,
you'll need to insert code to call another timer. Note that the
ANSI-standard function clock() rolls over after an hour or so, and is
therefore insufficient for timing long LAMMPS simulations.
</P>
<P>(3.c) The 3 FFT variables are used to specify an FFT library which
LAMMPS uses when using the particle-particle particle-mesh (PPPM)
option in LAMMPS for long-range Coulombics via the
<A HREF = "kspace_style.html">kspace_style</A> command.
</P>
<P>To use this option, you must have a 1d FFT library installed on your
platform. This is specified by a switch of the form -DFFT_XXX where
XXX = INTEL, DEC, SGI, SCSL, or FFTW. All but the last one are native
vendor-provided libraries. FFTW is a fast, portable library that
should work on any platform. You can download it from
<A HREF = "http://www.fftw.org">www.fftw.org</A>. Use version 2.1.X, not the newer
3.0.X. Building FFTW for your box should be as simple as ./configure;
make. Whichever FFT library you have on your platform, you'll need to
set the appropriate FFT_INC, FFT_PATH, and FFT_LIB variables in
-Makefile.foo.
+Makefile.foo, so the compiler and linker can find it.
</P>
<P>If you examine src/fft3d.c and src.fft3d.h you'll see it's possible to
add other vendor FFT libraries via #ifdef statements in the
appropriate places. If you successfully add a new FFT option, like
-DFFT_IBM, please send the LAMMPS developers an email; we'd like to
add it to LAMMPS.
</P>
<P>If you don't plan to use PPPM, you don't need an FFT library. In this
case you can set FFT_INC to -DFFT_NONE and leave the other 2 FFT
variables blank. Or you can exclude the KSPACE package when you build
LAMMPS (see below).
</P>
-<P>(3.d) The several SYSLIB and SYSPATH variables can be ignored unless
+<P>(3.d) The 3 JPG variables are used to specify a JPEG library which
+LAMMPS uses when writing a JPEG file via the <A HREF = "dump_image.html">dump
+image</A> command. These can be left blank if you are
+not using the -DLAMMPS_JPEG switch discussed above in section (3.a).
+</P>
+<P>A standard JPEG library usually goes by the name libjpeg.a and has an
+associated header file jpeglib.h. Whichever JPEG library you have on
+your platform, you'll need to set the appropriate JPG_INC, JPG_PATH,
+and JPG_LIB variables in Makefile.foo so that the compiler and linker
+can find it.
+</P>
+<P>(3.e) The several SYSLIB and SYSPATH variables can be ignored unless
you are building LAMMPS with one or more of the LAMMPS packages that
require these extra system libraries. The names of these packages are
the prefixes on the SYSLIB and SYSPATH variables. See the <A HREF = "#2_3_4">section
below</A> for more details. The SYSLIB variables list the system
libraries. The SYSPATH variables are where they are located on your
machine, which is typically only needed if they are in some
non-standard place, that is not in your library search path.
</P>
<P>That's it. Once you have a correct Makefile.foo and you have
pre-built any other libraries it will use (e.g. MPI, FFT, package
libraries), all you need to do from the src directory is type one of
these 2 commands:
</P>
<PRE>make foo
gmake foo
</PRE>
<P>You should get the executable lmp_foo when the build is complete.
</P>
<HR>
<A NAME = "2_2_5"></A><B><I>Additional build tips:</I></B>
<P>(1) Building LAMMPS for multiple platforms.
</P>
<P>You can make LAMMPS for multiple platforms from the same src
directory. Each target creates its own object sub-directory called
Obj_name where it stores the system-specific *.o files.
</P>
<P>(2) Cleaning up.
</P>
<P>Typing "make clean-all" or "make clean-foo" will delete *.o object
files created when LAMMPS is built, for either all builds or for a
particular machine.
</P>
<P>(3) Building for a Mac.
</P>
<P>OS X is BSD Unix, so it should just work. See the Makefile.mac file.
</P>
<P>(4) Building for MicroSoft Windows.
</P>
<P>The LAMMPS download page has an option to download a pre-built Windows
exeutable. See below for instructions for running this executable on
a Windows box.
</P>
<P>If the pre-built executable doesn't have the options you want, then
you should be able to build LAMMPS from source files on a Windows box.
I've never done this, but LAMMPS is just standard C++ with MPI and FFT
calls. You can use cygwin to build LAMMPS with a Unix make; see
Makefile.cygwin. Or you should be able to pull all the source files
into Visual C++ (ugh) or some similar development environment and
build it. In the src/MAKE/Windows directory are some notes from users
on how they built LAMMPS under Windows, so you can look at their
instructions for tips. Good luck - we can't help you on this one.
</P>
<P>(5) Changing the size limits in src/lmptype.h
</P>
<P>If you are running a very large problem (billions of atoms or more)
and get a run-time error about the system being too big, either on a
per-processor basis or in total size, then you may need to change one
or more settings in src/lmptype.h and re-compile LAMMPS.
</P>
<P>As the documentation in that file explains, you have basically
two choices to make:
</P>
<UL><LI>set the data type size of integer atom IDs to 4 or 8 bytes
<LI>set the data type size of integers that store the total system size to 4 or 8 bytes
</UL>
<P>The default for atom IDs is 4-byte integers since there is a memory
and communication cost for 8-byte integers. Non-molecular problems do
not need atom IDs so this does not restrict their size. Molecular
problems (which use IDs to define molecular topology), are limited to
about 2 billion atoms (2^31) with 4-byte IDs. With 8-byte IDs they
are effectively unlimited in size (2^63).
</P>
<P>The default for total system size quantities (like the number of atoms
or timesteps) is 8-byte integers by default which is effectively
unlimited in size (2^63). If your system does not support 8-byte
integers, an error will be generated, and you will need to set
"bigint" to 4-byte integers. This restricts your total system size to
about 2 billion atoms or timesteps (2^31).
</P>
<P>Note that in src/lmptype.h there are also settings for the MPI data
types associated with the integers that store atom IDs and total
system sizes, which need to be set consistent with the associated C
data types.
</P>
<P>In all cases, the size of problem that can be run on a per-processor
basis is limited by 4-byte integer storage to about 2 billion atoms
per processor (2^31), which should not normally be a restriction since
such a problem would have a huge per-processor memory footprint due to
neighbor lists and would run very slowly in terms of CPU
secs/timestep.
</P>
<HR>
<H4><A NAME = "2_3"></A>2.3 Making LAMMPS with optional packages
</H4>
<P>This section has the following sub-sections:
</P>
<UL><LI><A HREF = "#2_3_1">Package basics</A>
<LI><A HREF = "#2_3_2">Including/excluding packages</A>
<LI><A HREF = "#2_3_3">Packages that require extra LAMMPS libraries</A>
<LI><A HREF = "#2_3_4">Additional Makefile settings for extra libraries</A>
</UL>
<HR>
<A NAME = "2_3_1"></A><B><I>Package basics:</I></B>
<P>The source code for LAMMPS is structured as a large set of core files
which are always included, plus optional packages. Packages are
groups of files that enable a specific set of features. For example,
force fields for molecular systems or granular systems are in
packages. You can see the list of all packages by typing "make
package".
</P>
<P>The current list of standard packages is as follows:
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >asphere </TD><TD > aspherical particles and force fields</TD></TR>
<TR><TD >class2 </TD><TD > class 2 force fields</TD></TR>
<TR><TD >colloid </TD><TD > colloidal particle force fields</TD></TR>
<TR><TD >dipole </TD><TD > point dipole particles and force fields</TD></TR>
<TR><TD >dsmc </TD><TD > Direct Simulation Monte Carlo (DMSC) pair style</TD></TR>
<TR><TD >gpu </TD><TD > GPU-enabled force field styles</TD></TR>
<TR><TD >granular </TD><TD > force fields and boundary conditions for granular systems</TD></TR>
<TR><TD >kspace </TD><TD > long-range Ewald and particle-mesh (PPPM) solvers</TD></TR>
<TR><TD >manybody </TD><TD > metal, 3-body, bond-order potentials</TD></TR>
<TR><TD >meam </TD><TD > modified embedded atom method (MEAM) potential</TD></TR>
<TR><TD >molecule </TD><TD > force fields for molecular systems</TD></TR>
<TR><TD >opt </TD><TD > optimized versions of a few pair potentials</TD></TR>
<TR><TD >peri </TD><TD > Peridynamics model and potential</TD></TR>
<TR><TD >poems </TD><TD > coupled rigid body motion</TD></TR>
<TR><TD >reax </TD><TD > ReaxFF potential</TD></TR>
<TR><TD >replica </TD><TD > multi-replica methods</TD></TR>
<TR><TD >shock </TD><TD > methods for MD simulations of shock loading</TD></TR>
<TR><TD >srd </TD><TD > stochastic rotation dynamics (SRD)</TD></TR>
<TR><TD >xtc </TD><TD > dump atom snapshots in XTC format
</TD></TR></TABLE></DIV>
<P>There are also user-contributed packages which may be as simple as a
single additional file or many files grouped together which add a
specific functionality to the code.
</P>
<P>The difference between a <I>standard</I> package versus a <I>user</I> package is
as follows.
</P>
<P>Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LAMMPS.
</P>
<P>User packages don't necessarily meet these requirements. If you have
problems using a feature provided in a user package, you will likely
need to contact the contributor directly to get help. Information on
how to submit additions you make to LAMMPS as a user-contributed
package is given in <A HREF = "Section_modify.html#package">this section</A> of the
documentation.
</P>
<HR>
<A NAME = "2_3_2"></A><B><I>Including/excluding packages:</I></B>
<P>Any or all packages can be included or excluded independently BEFORE
LAMMPS is built.
</P>
<P>The two exceptions to this are the "gpu" and "opt" packages. Some of
the files in these packages require other packages to also be
included. If this is not the case, then those subsidiary files in
"gpu" and "opt" will not be installed either. To install all the
files in package "gpu", the "asphere" and "kspace" packages must also be
installed. To install all the files in package "opt", the "kspace" and
"manybody" packages must also be installed.
</P>
<P>You may wish to exclude certain packages if you will never run certain
kinds of simulations. This will keep you from having to build
auxiliary libraries (see below) and will produce a smaller executable
which may run a bit faster.
</P>
<P>By default, LAMMPS includes only the "kspace", "manybody", and
"molecule" packages.
</P>
<P>Packages are included or excluded by typing "make yes-name" or "make
no-name", where "name" is the name of the package. You can also type
"make yes-standard", "make no-standard", "make yes-user", "make
no-user", "make yes-all" or "make no-all" to include/exclude various
sets of packages. Type "make package" to see the various options.
</P>
<P>IMPORTANT NOTE: These make commands work by simply moving files back
and forth between the main src directory and sub-directories with the
package name, so that the files are seen or not seen when LAMMPS is
built. After you have included or excluded a package, you must
re-build LAMMPS.
</P>
<P>Additional make options exist to help manage LAMMPS files that exist
in both the src directory and in package sub-directories. You do not
normally need to use these commands unless you are editing LAMMPS
files or have downloaded a patch from the LAMMPS WWW site.
</P>
<P>Typing "make package-update" will overwrite src files with files from
the package directories if the package has been included. It should
be used after a patch is installed, since patches only update the
master package version of a file. Typing "make package-overwrite"
will overwrite files in the package directories with src files.
Typing "make package-check" will list differences between src and
package versions of the same files. Again, type "make package" to see
the various options.
</P>
<HR>
<A NAME = "2_3_3"></A><B><I>Packages that require extra LAMMPS libraries:</I></B>
<P>A few packages (standard or user) require that additional libraries be
compiled first, which LAMMPS will link to when it builds. The source
code for these libraries are included in the LAMMPS distribution under
the "lib" directory. Look at the README files in the lib directories
(e.g. lib/reax/README) for instructions on how to build each library.
</P>
<P>IMPORTANT NOTE: If you are including a package in your LAMMPS build
that uses one of these libraries, then you must build the library
BEFORE building LAMMPS itself, since the LAMMPS build will attempt to
link with the library file.
</P>
<P>Here is a bit of information about each library:
</P>
<P>The "atc" library in lib/atc is used by the user-atc package. It
provides continuum field estimation and molecular dynamics-finite
element coupling methods. It was written primarily by Reese Jones,
Jeremy Templeton and Jonathan Zimmerman at Sandia.
</P>
<P>The "gpu" library in lib/gpu is used by the gpu package. It
contains code to enable portions of LAMMPS to run on a GPU chip
associated with your CPU. Currently, only NVIDIA GPUs are supported.
Building this library requires NVIDIA Cuda tools to be installed on
your system. See the <A HREF = "#2_8">Running on GPUs</A> section below for more
info about installing and using Cuda.
</P>
<P>The "meam" library in lib/meam is used by the meam package.
computes the modified embedded atom method potential, which is a
generalization of EAM potentials that can be used to model a wider
variety of materials. This MEAM implementation was written by Greg
Wagner at Sandia. It requires a F90 compiler to build. The C++ to
FORTRAN function calls in pair_meam.cpp assumes that FORTRAN object
names are converted to C object names by appending an underscore
character. This is generally the case, but on machines that do not
conform to this convention, you will need to modify either the C++
code or your compiler settings.
</P>
<P>The "poems" library in lib/poems is used by the poems package.
computes the constrained rigid-body motion of articulated (jointed)
multibody systems. POEMS was written and is distributed by Prof Kurt
Anderson's group at Rensselaer Polytechnic Institute (RPI).
</P>
<P>The "reax" library in lib/reax is used by the reax package. It
computes the Reactive Force Field (ReaxFF) potential, developed by
Adri van Duin in Bill Goddard's group at CalTech. This implementation
in LAMMPS uses many of Adri's files and was developed by Aidan
Thompson at Sandia and Hansohl Cho at MIT. It requires a F77 or F90
compiler to build. The C++ to FORTRAN function calls in pair_reax.cpp
assume that FORTRAN object names are converted to C object names by
appending an underscore character. This is generally the case, but on
machines that do not conform to this convention, you will need to
modify either the C++ code or your compiler settings. The name
conversion is handled by the preprocessor macro called FORTRAN in
pair_reax_fortran.h. Different definitions of this macro can be
obtained by adding a machine-specific macro definition to the CCFLAGS
variable in your Makefile e.g. -D_IBM. See pair_reax_fortran.h for
more info.
</P>
<P>As described in its README file, each library is built by typing
something like
</P>
<PRE>make -f Makefile.g++
</PRE>
<P>in the appropriate directory, e.g. in lib/reax.
</P>
<P>You must use a Makefile that is a match for your system. If one of
the provided Makefiles is not appropriate for your system you will
need to edit or add one. For example, in the case of Fotran-based
libraries, your system must have a Fortran compiler, the settings for
which will be in the Makefile.
</P>
<HR>
<A NAME = "2_3_4"></A><B><I>Additional Makefile settings for extra libraries:</I></B>
<P>After the desired library or libraries are built, and the package has
been included, you can build LAMMPS itself. For example, from the
lammps/src directory you would type this, to build LAMMPS with ReaxFF.
Note that as discussed in the preceding section, the package library
itself, namely lib/reax/libreax.a, must already have been built, for
the LAMMPS build to be successful.
</P>
<PRE>make yes-reax
make g++
</PRE>
<P>Also note that simply building the library is not sufficient to use it
from LAMMPS. As in this example, you must also include the package
that uses and wraps the library before you build LAMMPS itself.
</P>
<P>As discussed in point (2.4) of <A HREF = "#2_2_4">this section</A> above, there are
settings in the low-level Makefile that specify additional system
libraries needed by individual LAMMPS add-on libraries. These are the
settings you must specify correctly in your low-level Makefile in
lammps/src/MAKE, such as Makefile.foo:
</P>
<P>To use the gpu package and library, the settings for gpu_SYSLIB and
gpu_SYSPATH must be correct. These are specific to the NVIDIA CUDA
software which must be installed on your system.
</P>
<P>To use the meam or reax packages and their libraries which are Fortran
based, the settings for meam_SYSLIB, reax_SYSLIB, meam_SYSPATH, and
reax_SYSPATH must be correct. This is so that the C++ compiler can
perform a cross-language link using the appropriate system Fortran
libraries.
</P>
<P>To use the user-atc package and library, the settings for
user-atc_SYSLIB and user-atc_SYSPATH must be correct. This is so that
the appropriate BLAS and LAPACK libs, used by the user-atc library,
can be found.
</P>
<HR>
<H4><A NAME = "2_4"></A>2.4 Building LAMMPS as a library
</H4>
<P>LAMMPS can be built as a library, which can then be called from
another application or a scripting language. See <A HREF = "Section_howto.html#4_10">this
section</A> for more info on coupling LAMMPS to
other codes. Building LAMMPS as a library is done by typing
</P>
<PRE>make makelib
make -f Makefile.lib foo
</PRE>
<P>where foo is the machine name. The first "make" command will create a
current Makefile.lib with all the file names in your src dir. The 2nd
"make" command will use it to build LAMMPS as a library. This
requires that Makefile.foo have a library target (lib) and
system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux
for an example. The build will create the file liblmp_foo.a which
another application can link to.
</P>
<P>When used from a C++ program, the library allows one or more LAMMPS
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within your application code, as needed.
</P>
<P>When used from a C or Fortran program or a scripting language, the
library has a simple function-style interface, provided in
src/library.cpp and src/library.h.
</P>
<P>See the sample codes couple/simple/simple.cpp and simple.c as examples
of C++ and C codes that invoke LAMMPS thru its library interface.
There are other examples as well in the couple directory which are
discussed in <A HREF = "Section_howto.html#4_10">this section</A> of the manual.
See <A HREF = "Section_python.html">this section</A> of the manual for a description
of the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface.
</P>
<P>The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See <A HREF = "Section_howto.html#4_19">this section</A> of the manual
for a description of the interface and how to extend it for your
needs.
</P>
<HR>
<H4><A NAME = "2_5"></A>2.5 Running LAMMPS
</H4>
<P>By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux
< in.file. This means you first create an input script (e.g. in.file)
containing the desired commands. <A HREF = "Section_commands.html">This section</A>
describes how input scripts are structured and what commands they
contain.
</P>
<P>You can test LAMMPS on any of the sample inputs provided in the
examples or bench directory. Input scripts are named in.* and sample
outputs are named log.*.name.P where name is a machine and P is the
number of processors it was run on.
</P>
<P>Here is how you might run a standard Lennard-Jones benchmark on a
Linux box, using mpirun to launch a parallel job:
</P>
<PRE>cd src
make linux
cp lmp_linux ../bench
cd ../bench
mpirun -np 4 lmp_linux < in.lj
</PRE>
<P>See <A HREF = "http://lammps.sandia.gov/bench.html">this page</A> for timings for this and the other benchmarks
on various platforms.
</P>
<HR>
<P>On a Windows machine, you can skip making LAMMPS and simply download
an executable. But note that not all packages are available.
The following packages are available: asphere, class2, colloid, dipole,
dsmc, granular, kspace, manybody, molecule, peri, poems, replica, shock,
user-ackland, user-cd-eam, user-cg-cmm, user-ewaldn, user-smd. But these
packages are not available: gpu, meam, opt, reax, xtc, user-atc, user-imd.
</P>
<P>To run the LAMMPS executable on a Windows machine, first decide whether
you want to download the non-MPI (serial) or the MPI (parallel) version
of the executable. Download and save the version you have chosen.
</P>
<P>For the non-MPI version, follow these steps:
</P>
<UL><LI>Get a command prompt by going to Start->Run... ,
then typing "cmd".
<LI>Move to the directory where you have saved lmp_win_no-mpi.exe
(e.g. by typing: cd "Documents").
<LI>At the command prompt, type "lmp_win_no-mpi -in in.lj", replacing in.lj
with the name of your LAMMPS input script.
</UL>
<P>For the MPI version, which allows you to run LAMMPS under Windows on
multiple processors, follow these steps:
</P>
<UL><LI>Download and install
<A HREF = "http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads">MPICH2</A>
for Windows.
<LI>You'll need to use the mpiexec.exe and smpd.exe files from the MPICH2 package. Put them in
same directory (or path) as the LAMMPS Windows executable.
<LI>Get a command prompt by going to Start->Run... ,
then typing "cmd".
<LI>Move to the directory where you have saved lmp_win_mpi.exe
(e.g. by typing: cd "Documents").
<LI>Then type something like this: "mpiexec -np 4 -localonly lmp_win_mpi -in in.lj",
replacing in.lj with the name of your LAMMPS input script.
<LI>Note that you may need to provide smpd with a passphrase --- it doesn't matter what you
type.
<LI>In this mode, output may not immediately show up on the screen, so
if your input script takes a long time to execute, you may need to be
patient before the output shows up.
<LI>Alternatively, you can still use this executable to run on a single processor by
typing something like: "lmp_win_mpi -in in.lj".
</UL>
<HR>
<P>The screen output from LAMMPS is described in the next section. As it
runs, LAMMPS also writes a log.lammps file with the same information.
</P>
<P>Note that this sequence of commands copies the LAMMPS executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from (if you launch lmp_linux on its own and not
under mpirun). If that happens, LAMMPS will look for additional input
files and write its output files to the executable directory, rather
than your working directory, which is probably not what you want.
</P>
<P>If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See <A HREF = "Section_errors.html">this section</A> for a
discussion of the various kinds of errors LAMMPS can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
</P>
<P>LAMMPS can run a problem on any number of processors, including a
single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories.
</P>
<P>LAMMPS can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or setup a smaller problem.
</P>
<HR>
<H4><A NAME = "2_6"></A>2.6 Command-line options
</H4>
<P>At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. Either the full word or the
one-letter abbreviation can be used:
</P>
<UL><LI>-echo or -e
<LI>-partition or -p
<LI>-in or -i
<LI>-log or -l
<LI>-screen or -s
<LI>-var or -v
</UL>
<P>For example, lmp_ibm might be launched as follows:
</P>
<PRE>mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none < in.alloy
</PRE>
<P>Here are the details on the options:
</P>
<PRE>-echo style
</PRE>
<P>Set the style of command echoing. The style can be <I>none</I> or <I>screen</I>
or <I>log</I> or <I>both</I>. Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile. This
can be useful to figure out which line of your script is causing an
input error. The default value is <I>log</I>. The echo style can also be
set by using the <A HREF = "echo.html">echo</A> command in the input script itself.
</P>
<PRE>-partition 8x2 4 5 ...
</PRE>
<P>Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P
processors and this switch is not used, LAMMPS runs in one partition,
i.e. all P processors run a single simulation. If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation. The arguments to the switch
specify the number of processors in each partition. Arguments of the
form MxN mean M partitions, each with N processors. Arguments of the
form N mean a single partition with N processors. The sum of
processors in all partitions must equal P. Thus the command
"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
processors.
</P>
<P>Note that with MPI installed on a machine (e.g. your desktop), you can
run on more (virtual) processors than you have physical processors.
This can be useful for running <A HREF = "Section_howto.html#4_5">multi-replica
simulations</A>, on one or a few processors.
</P>
<P>The input script specifies what simulation is run on which partition;
see the <A HREF = "variable.html">variable</A> and <A HREF = "next.html">next</A> commands. This
<A HREF = "Section_howto.html#4_4">howto section</A> gives examples of how to use
these commands in this way. Simulations running on different
partitions can also communicate with each other; see the
<A HREF = "temper.html">temper</A> command.
</P>
<PRE>-in file
</PRE>
<P>Specify a file to use as an input script. This is an optional switch
when running LAMMPS in one-partition mode. If it is not specified,
LAMMPS reads its input script from stdin - e.g. lmp_linux < in.run.
This is a required switch when running LAMMPS in multi-partition mode,
since multiple processors cannot all read from stdin.
</P>
<PRE>-log file
</PRE>
<P>Specify a log file for LAMMPS to write status information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
file log.lammps. If this switch is used, LAMMPS writes to the
specified file. In multi-partition mode, if the switch is not used, a
log.lammps file is created with hi-level status information. Each
partition also writes to a log.lammps.N file where N is the partition
ID. If the switch is specified in multi-partition mode, the hi-level
logfile is named "file" and each partition also logs information to a
file.N. For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created. Using a
<A HREF = "log.html">log</A> command in the input script will override this setting.
</P>
<PRE>-screen file
</PRE>
<P>Specify a file for LAMMPS to write its screen information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
screen. If this switch is used, LAMMPS writes to the specified file
instead and you will see no screen output. In multi-partition mode,
if the switch is not used, hi-level status information is written to
the screen. Each partition also writes to a screen.N file where N is
the partition ID. If the switch is specified in multi-partition mode,
the hi-level screen dump is named "file" and each partition also
writes screen information to a file.N. For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed.
</P>
<PRE>-var name value1 value2 ...
</PRE>
<P>Specify a variable that will be defined for substitution purposes when
the input script is read. "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as ${abc}). An <A HREF = "variable.html">index-style
variable</A> will be created and populated with the
subsequent values, e.g. a set of filenames. Using this command-line
option is equivalent to putting the line "variable name index value1
value2 ..." at the beginning of the input script. Defining an index
variable as a command-line argument overrides any setting for the same
index variable in the input script, since index variables cannot be
re-defined. See the <A HREF = "variable.html">variable</A> command for more info on
defining index and other kinds of variables and <A HREF = "Section_commands.html#3_2">this
section</A> for more info on using variables in
input scripts.
</P>
<HR>
<H4><A NAME = "2_7"></A>2.7 LAMMPS screen output
</H4>
<P>As LAMMPS reads an input script, it prints information to both the
screen and a log file about significant actions it takes to setup a
simulation. When the simulation is ready to begin, LAMMPS performs
various initializations and prints the amount of memory (in MBytes per
processor) that the simulation requires. It also prints details of
the initial thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few
timesteps. When the run concludes, LAMMPS prints the final
thermodynamic state and a total run time for the simulation. It then
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:
</P>
<PRE>Loop time of 49.002 on 2 procs for 2004 atoms
</PRE>
<PRE>Pair time (%) = 35.0495 (71.5267)
Bond time (%) = 0.092046 (0.187841)
Kspce time (%) = 6.42073 (13.103)
Neigh time (%) = 2.73485 (5.5811)
Comm time (%) = 1.50291 (3.06703)
Outpt time (%) = 0.013799 (0.0281601)
Other time (%) = 2.13669 (4.36041)
</PRE>
<PRE>Nlocal: 1002 ave, 1015 max, 989 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8720 ave, 8724 max, 8716 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354141 ave, 361422 max, 346860 min
Histogram: 1 0 0 0 0 0 0 0 0 1
</PRE>
<PRE>Total # of neighbors = 708282
Ave neighs/atom = 353.434
Ave special neighs/atom = 2.34032
Number of reneighborings = 42
Dangerous reneighborings = 2
</PRE>
<P>The first section gives the breakdown of the CPU run time (in seconds)
into major categories. The second section lists the number of owned
atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
per processor. The max and min values give the spread of these values
across processors with a 10-bin histogram showing the distribution.
The total number of histogram counts is equal to the number of
processors.
</P>
<P>The last section gives aggregate statistics for pair-wise neighbors
and special neighbors that LAMMPS keeps track of (see the
<A HREF = "special_bonds.html">special_bonds</A> command). The number of times
neighbor lists were rebuilt during the run is given as well as the
number of potentially "dangerous" rebuilds. If atom movement
triggered neighbor list rebuilding (see the
<A HREF = "neigh_modify.html">neigh_modify</A> command), then dangerous
reneighborings are those that were triggered on the first timestep
atom movement was checked for. If this count is non-zero you may wish
to reduce the delay factor to insure no force interactions are missed
by atoms moving beyond the neighbor skin distance before a rebuild
takes place.
</P>
<P>If an energy minimization was performed via the
<A HREF = "minimize.html">minimize</A> command, additional information is printed,
e.g.
</P>
<PRE>Minimization stats:
E initial, next-to-last, final = -0.895962 -2.94193 -2.94342
Gradient 2-norm init/final= 1920.78 20.9992
Gradient inf-norm init/final= 304.283 9.61216
Iterations = 36
Force evaluations = 177
</PRE>
<P>The first line lists the initial and final energy, as well as the
energy on the next-to-last iteration. The next 2 lines give a measure
of the gradient of the energy (force on all atoms). The 2-norm is the
"length" of this force vector; the inf-norm is the largest component.
The last 2 lines are statistics on how many iterations and
force-evaluations the minimizer required. Multiple force evaluations
are typically done at each iteration to perform a 1d line minimization
in the search direction.
</P>
<P>If a <A HREF = "kspace_style.html">kspace_style</A> long-range Coulombics solve was
performed during the run (PPPM, Ewald), then additional information is
printed, e.g.
</P>
<PRE>FFT time (% of Kspce) = 0.200313 (8.34477)
FFT Gflps 3d 1d-only = 2.31074 9.19989
</PRE>
<P>The first line gives the time spent doing 3d FFTs (4 per timestep) and
the fraction it represents of the total KSpace time (listed above).
Each 3d FFT requires computation (3 sets of 1d FFTs) and communication
(transposes). The total flops performed is 5Nlog_2(N), where N is the
number of points in the 3d grid. The FFTs are timed with and without
the communication and a Gflop rate is computed. The 3d rate is with
communication; the 1d rate is without (just the 1d FFTs). Thus you
can estimate what fraction of your FFT time was spent in
communication, roughly 75% in the example above.
</P>
<HR>
<H4><A NAME = "2_8"></A>2.8 Running on GPUs
</H4>
<P>A few LAMMPS <A HREF = "pair_style.html">pair styles</A> can be run on graphical
processing units (GPUs). We plan to add more over time. Currently,
they only support NVIDIA GPU cards. To use them you need to install
certain NVIDIA CUDA software on your system:
</P>
<UL><LI>Check if you have an NVIDIA card: cat /proc/driver/nvidia/cards/0
<LI>Go to http://www.nvidia.com/object/cuda_get.html
<LI>Install a driver and toolkit appropriate for your system (SDK is not necessary)
<LI>Follow the instructions in README in lammps/lib/gpu to build the library.
<LI>Run lammps/lib/gpu/nvc_get_devices to list supported devices and properties
</UL>
<H4>GPU configuration
</H4>
<P>When using GPUs, you are restricted to one physical GPU per LAMMPS
process. Multiple processes can share a single GPU and in many cases it
will be more efficient to run with multiple processes per GPU. Any GPU
accelerated style requires that <A HREF = "fix_gpu.html">fix gpu</A> be used in the
input script to select and initialize the GPUs. The format for the fix
is:
</P>
<PRE>fix <I>name</I> all gpu <I>mode</I> <I>first</I> <I>last</I> <I>split</I>
</PRE>
<P>where <I>name</I> is the name for the fix. The gpu fix must be the first
fix specified for a given run, otherwise the program will exit
with an error. The gpu fix will not have any effect on runs
that do not use GPU acceleration; there should be no problem
with specifying the fix first in any input script.
</P>
<P><I>mode</I> can be either "force" or "force/neigh". In the former,
neighbor list calculation is performed on the CPU using the
standard LAMMPS routines. In the latter, the neighbor list
calculation is performed on the GPU. The GPU neighbor list
can be used for better performance, however, it
should not be used with a triclinic box.
</P>
<P>There are cases when it might be more efficient to select the CPU for neighbor
list builds. If a non-GPU enabled style requires a neighbor list, it will also
be built using CPU routines. Redundant CPU and GPU neighbor list calculations
will typically be less efficient. For <A HREF = "pair_hybrid.html">hybrid</A> pair
styles, GPU calculated neighbor lists might be less efficient because
no particles will be skipped in a given neighbor list.
</P>
<P><I>first</I> is the ID (as reported by lammps/lib/gpu/nvc_get_devices)
of the first GPU that will be used on each node. <I>last</I> is the
ID of the last GPU that will be used on each node. If you have
only one GPU per node, <I>first</I> and <I>last</I> will typically both be
0. Selecting a non-sequential set of GPU IDs (e.g. 0,1,3)
is not currently supported.
</P>
<P><I>split</I> is the fraction of particles whose forces, torques,
energies, and/or virials will be calculated on the GPU. This
can be used to perform CPU and GPU force calculations
simultaneously. If <I>split</I> is negative, the software will
attempt to calculate the optimal fraction automatically
every 25 timesteps based on CPU and GPU timings. Because the GPU speedups
are dependent on the number of particles, automatic calculation of the
split can be less efficient, but typically results in loop times
within 20% of an optimal fixed split.
</P>
<P>If you have two GPUs per node, 8 CPU cores per node, and
would like to run on 4 nodes with dynamic balancing of
force calculation across CPU and GPU cores, the fix
might be
</P>
<PRE>fix 0 all gpu force/neigh 0 1 -1
</PRE>
<P>with LAMMPS run on 32 processes. In this case, all
CPU cores and GPU devices on the nodes would be utilized.
Each GPU device would be shared by 4 CPU cores. The
CPU cores would perform force calculations for some
fraction of the particles at the same time the GPUs
performed force calculation for the other particles.
</P>
<P>Because of the large number of cores on each GPU
device, it might be more efficient to run on fewer
processes per GPU when the number of particles per process
is small (100's of particles); this can be necessary
to keep the GPU cores busy.
</P>
<H4>GPU input script
</H4>
<P>In order to use GPU acceleration in LAMMPS,
<A HREF = "fix_gpu.html">fix_gpu</A>
should be used in order to initialize and configure the
GPUs for use. Additionally, GPU enabled styles must be
selected in the input script. Currently,
this is limited to a few <A HREF = "pair_style.html">pair styles</A>.
Some GPU-enabled styles have additional restrictions
listed in their documentation.
</P>
<H4>GPU asynchronous pair computation
</H4>
<P>The GPU accelerated pair styles can be used to perform
pair style force calculation on the GPU while other
calculations are
performed on the CPU. One method to do this is to specify
a <I>split</I> in the gpu fix as described above. In this case,
force calculation for the pair style will also be performed
on the CPU.
</P>
<P>When the CPU work in a GPU pair style has finished,
the next force computation will begin, possibly before the
GPU has finished. If <I>split</I> is 1.0 in the gpu fix, the next
force computation will begin almost immediately. This can
be used to run a <A HREF = "pair_hybrid.html">hybrid</A> GPU pair style at
the same time as a hybrid CPU pair style. In this case, the
GPU pair style should be first in the hybrid command in order to
perform simultaneous calculations. This also
allows <A HREF = "bond_style.html">bond</A>, <A HREF = "angle_style.html">angle</A>,
<A HREF = "dihedral_style.html">dihedral</A>, <A HREF = "improper_style.html">improper</A>,
and <A HREF = "kspace_style.html">long-range</A> force
computations to be run simultaneously with the GPU pair style.
Once all CPU force computations have completed, the gpu fix
will block until the GPU has finished all work before continuing
the run.
</P>
<H4>GPU timing
</H4>
<P>GPU accelerated pair styles can perform computations asynchronously
with CPU computations. The "Pair" time reported by LAMMPS
will be the maximum of the time required to complete the CPU
pair style computations and the time required to complete the GPU
pair style computations. Any time spent for GPU-enabled pair styles
for computations that run simultaneously with <A HREF = "bond_style.html">bond</A>,
<A HREF = "angle_style.html">angle</A>, <A HREF = "dihedral_style.html">dihedral</A>,
<A HREF = "improper_style.html">improper</A>, and <A HREF = "kspace_style.html">long-range</A> calculations
will not be included in the "Pair" time.
</P>
<P>When <I>mode</I> for the gpu fix is force/neigh,
the time for neighbor list calculations on the GPU will be added
into the "Pair" time, not the "Neigh" time. A breakdown of the
times required for various tasks on the GPU (data copy, neighbor
calculations, force computations, etc.) are output only
with the LAMMPS screen output at the end of each run. These timings represent
total time spent on the GPU for each routine, regardless of asynchronous
CPU calculations.
</P>
<H4>GPU single vs double precision
</H4>
<P>See the lammps/lib/gpu/README file for instructions on how to build
the LAMMPS gpu library for single, mixed, and double precision. The latter
requires that your GPU card supports double precision.
</P>
<HR>
<H4><A NAME = "2_9"></A>2.9 Tips for users of previous LAMMPS versions
</H4>
<P>The current C++ began with a complete rewrite of LAMMPS 2001, which
was written in F90. Features of earlier versions of LAMMPS are listed
in <A HREF = "Section_history.html">this section</A>. The F90 and F77 versions
(2001 and 99) are also freely distributed as open-source codes; check
the <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> for distribution information if you prefer
those versions. The 99 and 2001 versions are no longer under active
development; they do not have all the features of C++ LAMMPS.
</P>
<P>If you are a previous user of LAMMPS 2001, these are the most
significant changes you will notice in C++ LAMMPS:
</P>
<P>(1) The names and arguments of many input script commands have
changed. All commands are now a single word (e.g. read_data instead
of read data).
</P>
<P>(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS,
but you may need to specify the relevant commands in different ways.
</P>
<P>(3) The format of the data file can be streamlined for some problems.
See the <A HREF = "read_data.html">read_data</A> command for details. The data file
section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS.
</P>
<P>(4) Binary restart files written by LAMMPS 2001 cannot be read by C++
LAMMPS with a <A HREF = "read_restart.html">read_restart</A> command. This is
because they were output by F90 which writes in a different binary
format than C or C++ writes or reads. Use the <I>restart2data</I> tool
provided with LAMMPS 2001 to convert the 2001 restart file to a text
data file. Then edit the data file as necessary before using the C++
LAMMPS <A HREF = "read_data.html">read_data</A> command to read it in.
</P>
<P>(5) There are numerous small numerical changes in C++ LAMMPS that mean
you will not get identical answers when comparing to a 2001 run.
However, your initial thermodynamic energy and MD trajectory should be
close if you have setup the problem for both codes the same.
</P>
</HTML>
diff --git a/doc/Section_start.txt b/doc/Section_start.txt
index 10a5a3ba8..4b4d96693 100644
--- a/doc/Section_start.txt
+++ b/doc/Section_start.txt
@@ -1,1130 +1,1162 @@
"Previous Section"_Section_intro.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_commands.html :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
2. Getting Started :h3
This section describes how to build and run LAMMPS, for both new and
experienced users.
2.1 "What's in the LAMMPS distribution"_#2_1
2.2 "Making LAMMPS"_#2_2
2.3 "Making LAMMPS with optional packages"_#2_3
2.4 "Building LAMMPS as a library"_#2_4
2.5 "Running LAMMPS"_#2_5
2.6 "Command-line options"_#2_6
2.7 "Screen output"_#2_7
2.8 "Running on GPUs"_#2_8
2.9 "Tips for users of previous versions"_#2_9 :all(b)
:line
2.1 What's in the LAMMPS distribution :h4,link(2_1)
When you download LAMMPS you will need to unzip and untar the
downloaded file with the following commands, after placing the file in
an appropriate directory.
gunzip lammps*.tar.gz
tar xvf lammps*.tar :pre
This will create a LAMMPS directory containing two files and several
sub-directories:
README: text file
LICENSE: the GNU General Public License (GPL)
bench: benchmark problems
couple: code coupling examples, using LAMMPS as a library
doc: documentation
examples: simple test problems
potentials: embedded atom method (EAM) potential files
src: source files
tools: pre- and post-processing tools :tb(s=:)
If you download the Windows executable from the download page,
then you just get a single file:
lmp_windows.exe :pre
Skip to the "Running LAMMPS"_#2_5 section, to learn how to launch this
executable on a Windows box.
The Windows executable also only includes certain packages and
bug-fixes/upgrades listed on "this
page"_http://lammps.sandia.gov/bug.html up to a certain date, as
stated on the download page. If you want something with more packages
or that is more current, you'll have to download the source tarball
and build it yourself, as described in the next section.
:line
2.2 Making LAMMPS :h4,link(2_2)
This section has the following sub-sections:
"Read this first"_#2_2_1
"Building a LAMMPS executable"_#2_2_2
"Common errors that can occur when making LAMMPS"_#2_2_3
"Editing a new low-level Makefile"_#2_2_4
"Additional build tips"_#2_2_5 :ul
:line
[{Read this first:}] :link(2_2_1)
Building LAMMPS can be non-trivial. You will likely need to edit a
makefile, there are compiler options, additional libraries can be used
-(MPI, FFT), etc. Please read this section carefully. If you are not
-comfortable with makefiles, or building codes on a Unix platform, or
-running an MPI job on your machine, please find a local expert to help
-you. Many compiling, linking, and run problems that users are not
-really LAMMPS issues - they are peculiar to the user's system,
-compilers, libraries, etc. Such questions are better answered by a
-local expert.
+(MPI, FFT, JPEG), etc. Please read this section carefully. If you
+are not comfortable with makefiles, or building codes on a Unix
+platform, or running an MPI job on your machine, please find a local
+expert to help you. Many compiling, linking, and run problems that
+users are not really LAMMPS issues - they are peculiar to the user's
+system, compilers, libraries, etc. Such questions are better answered
+by a local expert.
If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
please send an email to the
"developers"_http://lammps.sandia.gov/authors.html.
If you succeed in building LAMMPS on a new kind of machine, for which
there isn't a similar Makefile for in the src/MAKE directory, send it
to the developers and we'll include it in future LAMMPS releases.
:line
[{Building a LAMMPS executable:}] :link(2_2_2)
The src directory contains the C++ source and header files for LAMMPS.
It also contains a top-level Makefile and a MAKE sub-directory with
low-level Makefile.* files for several machines. From within the src
directory, type "make" or "gmake". You should see a list of available
choices. If one of those is the machine and options you want, you can
type a command like:
make linux
gmake mac :pre
Note that on a multi-processor or multi-core platform you can launch a
parallel make, by using the "-j" switch with the make command, which
will build LAMMPS more quickly.
If you get no errors and an executable like lmp_linux or lmp_mac is
produced, you're done; it's your lucky day.
:line
[{Common errors that can occur when making LAMMPS:}] :link(2_2_3)
(1) If the make command breaks immediately with errors that indicate
it can't find files with a "*" in their names, this can be because
your machine's make doesn't support wildcard expansion in a makefile.
Try gmake instead of make. If that doesn't work, try using a -f
switch with your make command to use Makefile.list which explicitly
lists all the needed files, e.g.
make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac :pre
The first "make" command will create a current Makefile.list with all
the file names in your src dir. The 2nd "make" command (make or
gmake) will use it to build LAMMPS.
(2) Other errors typically occur because the low-level Makefile isn't
setup correctly for your machine. If your platform is named "foo",
you will need to create a Makefile.foo in the MAKE sub-directory. Use
whatever existing file is closest to your platform as a starting
point. See the next section for more instructions.
(3) If you get a link-time error about missing libraries or missing
dependencies, then it can be because:
you are including a package that needs an extra library, but have not pre-built the necessary "package library"_#2_3_3
you are linking to a library that doesn't exist on your system
you are not linking to the necessary system library :ul
The first issue is discussed below. The other two issue mean you need
to edit your low-level Makefile.foo, as discussed in the next
sub-section.
:line
[{Editing a new low-level Makefile.foo:}] :link(2_2_4)
These are the issues you need to address when editing a low-level
Makefile for your machine. The portions of the file you typically
need to edit are the first line, the "compiler/linker settings"
section, and the "system-specific settings" section.
(1) Change the first line of Makefile.foo to list the word "foo" after
the "#", and whatever other options you set. This is the line you
will see if you just type "make".
(3) The "compiler/linker settings" section lists compiler and linker
settings for your C++ compiler, including optimization flags. You can
use g++, the open-source GNU compiler, which is available on all Unix
systems. You can also use mpicc which will typically be available if
MPI is installed on your system, though you should check which actual
compiler it wraps. Vendor compilers often produce faster code. On
boxes with Intel CPUs, we suggest using the free Intel icc compiler,
which you can download from "Intel's compiler site"_intel.
:link(intel,http://www.intel.com/software/products/noncom)
If building a C++ code on your machine requires additional libraries,
then you should list them as part of the LIB variable.
The DEPFLAGS setting is what triggers the C++ compiler to create a
dependency list for a source file. This speeds re-compilation when
source (*.cpp) or header (*.h) files are edited. Some compilers do
not support dependency file creation, or may use a different switch
than -D. GNU g++ works with -D. If your compiler can't create
dependency files (a long list of errors involving *.d files), then
you'll need to create a Makefile.foo patterned after Makefile.storm,
which uses different rules that do not involve dependency files.
(3) The "system-specific settings" section has 4 parts.
(3.a) The LMP_INC variable is used to include options that turn on
-system-dependent ifdefs within the LAMMPS code.
+system-dependent ifdefs within the LAMMPS code. The settings
+that are currently recogized are:
+
+-DLAMMPS_GZIP
+-DPACK_ARRAY
+-DPACK_POINTER
+-DPACK_MEMCPY
+-DLAMMPS_XDR
+-DLAMMPS_JPEG :ul
The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It requires that your Unix support the
-"popen" command. Using one of the -DPACK_ARRAY, -DPACK_POINTER, and
--DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM
-solver) on some platforms. The -DPACK_ARRAY setting is the default.
+"popen" command.
+
+Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
+options can make for faster parallel FFTs (in the PPPM solver) on some
+platforms. The -DPACK_ARRAY setting is the default. See the
+"kspace_style"_kspace_style.html command for info about PPPM. See
+section (3.c) below for info about building LAMMPS with an FFT
+library.
+
If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the "dump"_dump.html command for details.
+If you use -DLAMMPS_JPEG, the "dump image"_dump.html command will be
+able to write out JPEG image files. If not, it will only be able to
+write out PPM image files. For JPEG files, you must also link LAMMPS
+with a JPEG library. See section (3.d) below for more details on
+this.
+
(3.b) The 3 MPI variables are used to specify an MPI library to build
LAMMPS with.
If you want LAMMPS to run in parallel, you must have an MPI library
installed on your platform. If you use an MPI-wrapped compiler, such
as "mpicc" to build LAMMPS, you can probably leave these 3 variables
blank. If you do not use "mpicc" as your compiler/linker, then you
need to specify where the mpi.h file (MPI_INC) and the MPI library
(MPI_PATH) is found and its name (MPI_LIB).
If you are installing MPI yourself, we recommend Argonne's MPICH 1.2
-or 2.0 which can be downloaded from the "Argonne MPI
-site"_http://www-unix.mcs.anl.gov/mpi. LAM MPI should also work. If
+or 2.0 or OpenMPI. MPICH can be downloaded from the "Argonne MPI
+site"_http://www-unix.mcs.anl.gov/mpi. OpenMPI can be downloaded the
+"OpenMPI site"_http://www.open-mpi.org. LAM MPI should also work. If
you are running on a big parallel platform, your system people or the
vendor should have already installed a version of MPI, which will be
-faster than MPICH or LAM, so find out how to build and link with it.
-If you use MPICH or LAM, you will have to configure and build it for
-your platform. The MPI configure script should have compiler options
-to enable you to use the same compiler you are using for the LAMMPS
-build, which can avoid problems that can arise when linking LAMMPS to
-the MPI library.
+faster than MPICH or OpenMPI or LAM, so find out how to build and link
+with it. If you use MPICH or OpenMPI or LAM, you will have to
+configure and build it for your platform. The MPI configure script
+should have compiler options to enable you to use the same compiler
+you are using for the LAMMPS build, which can avoid problems that can
+arise when linking LAMMPS to the MPI library.
If you just want LAMMPS to run on a single processor, you can use the
-STUBS library in place of MPI, since you don't need an MPI library
+STUBS library in place of MPI, since you don't need a true MPI library
installed on your system. See the Makefile.serial file for how to
specify the 3 MPI variables. You will also need to build the STUBS
library for your platform before making LAMMPS itself. From the STUBS
dir, type "make" and it will hopefully create a libmpi.a suitable for
linking to LAMMPS. If this build fails, you will need to edit the
STUBS/Makefile for your platform.
The file STUBS/mpi.cpp has a CPU timer function MPI_Wtime() that calls
gettimeofday() . If your system doesn't support gettimeofday() ,
you'll need to insert code to call another timer. Note that the
ANSI-standard function clock() rolls over after an hour or so, and is
therefore insufficient for timing long LAMMPS simulations.
(3.c) The 3 FFT variables are used to specify an FFT library which
LAMMPS uses when using the particle-particle particle-mesh (PPPM)
option in LAMMPS for long-range Coulombics via the
"kspace_style"_kspace_style.html command.
To use this option, you must have a 1d FFT library installed on your
platform. This is specified by a switch of the form -DFFT_XXX where
XXX = INTEL, DEC, SGI, SCSL, or FFTW. All but the last one are native
vendor-provided libraries. FFTW is a fast, portable library that
should work on any platform. You can download it from
"www.fftw.org"_http://www.fftw.org. Use version 2.1.X, not the newer
3.0.X. Building FFTW for your box should be as simple as ./configure;
make. Whichever FFT library you have on your platform, you'll need to
set the appropriate FFT_INC, FFT_PATH, and FFT_LIB variables in
-Makefile.foo.
+Makefile.foo, so the compiler and linker can find it.
If you examine src/fft3d.c and src.fft3d.h you'll see it's possible to
add other vendor FFT libraries via #ifdef statements in the
appropriate places. If you successfully add a new FFT option, like
-DFFT_IBM, please send the LAMMPS developers an email; we'd like to
add it to LAMMPS.
If you don't plan to use PPPM, you don't need an FFT library. In this
case you can set FFT_INC to -DFFT_NONE and leave the other 2 FFT
variables blank. Or you can exclude the KSPACE package when you build
LAMMPS (see below).
-(3.d) The several SYSLIB and SYSPATH variables can be ignored unless
+(3.d) The 3 JPG variables are used to specify a JPEG library which
+LAMMPS uses when writing a JPEG file via the "dump
+image"_dump_image.html command. These can be left blank if you are
+not using the -DLAMMPS_JPEG switch discussed above in section (3.a).
+
+A standard JPEG library usually goes by the name libjpeg.a and has an
+associated header file jpeglib.h. Whichever JPEG library you have on
+your platform, you'll need to set the appropriate JPG_INC, JPG_PATH,
+and JPG_LIB variables in Makefile.foo so that the compiler and linker
+can find it.
+
+(3.e) The several SYSLIB and SYSPATH variables can be ignored unless
you are building LAMMPS with one or more of the LAMMPS packages that
require these extra system libraries. The names of these packages are
the prefixes on the SYSLIB and SYSPATH variables. See the "section
below"_#2_3_4 for more details. The SYSLIB variables list the system
libraries. The SYSPATH variables are where they are located on your
machine, which is typically only needed if they are in some
non-standard place, that is not in your library search path.
That's it. Once you have a correct Makefile.foo and you have
pre-built any other libraries it will use (e.g. MPI, FFT, package
libraries), all you need to do from the src directory is type one of
these 2 commands:
make foo
gmake foo :pre
You should get the executable lmp_foo when the build is complete.
:line
[{Additional build tips:}] :link(2_2_5)
(1) Building LAMMPS for multiple platforms.
You can make LAMMPS for multiple platforms from the same src
directory. Each target creates its own object sub-directory called
Obj_name where it stores the system-specific *.o files.
(2) Cleaning up.
Typing "make clean-all" or "make clean-foo" will delete *.o object
files created when LAMMPS is built, for either all builds or for a
particular machine.
(3) Building for a Mac.
OS X is BSD Unix, so it should just work. See the Makefile.mac file.
(4) Building for MicroSoft Windows.
The LAMMPS download page has an option to download a pre-built Windows
exeutable. See below for instructions for running this executable on
a Windows box.
If the pre-built executable doesn't have the options you want, then
you should be able to build LAMMPS from source files on a Windows box.
I've never done this, but LAMMPS is just standard C++ with MPI and FFT
calls. You can use cygwin to build LAMMPS with a Unix make; see
Makefile.cygwin. Or you should be able to pull all the source files
into Visual C++ (ugh) or some similar development environment and
build it. In the src/MAKE/Windows directory are some notes from users
on how they built LAMMPS under Windows, so you can look at their
instructions for tips. Good luck - we can't help you on this one.
(5) Changing the size limits in src/lmptype.h
If you are running a very large problem (billions of atoms or more)
and get a run-time error about the system being too big, either on a
per-processor basis or in total size, then you may need to change one
or more settings in src/lmptype.h and re-compile LAMMPS.
As the documentation in that file explains, you have basically
two choices to make:
set the data type size of integer atom IDs to 4 or 8 bytes
set the data type size of integers that store the total system size to 4 or 8 bytes :ul
The default for atom IDs is 4-byte integers since there is a memory
and communication cost for 8-byte integers. Non-molecular problems do
not need atom IDs so this does not restrict their size. Molecular
problems (which use IDs to define molecular topology), are limited to
about 2 billion atoms (2^31) with 4-byte IDs. With 8-byte IDs they
are effectively unlimited in size (2^63).
The default for total system size quantities (like the number of atoms
or timesteps) is 8-byte integers by default which is effectively
unlimited in size (2^63). If your system does not support 8-byte
integers, an error will be generated, and you will need to set
"bigint" to 4-byte integers. This restricts your total system size to
about 2 billion atoms or timesteps (2^31).
Note that in src/lmptype.h there are also settings for the MPI data
types associated with the integers that store atom IDs and total
system sizes, which need to be set consistent with the associated C
data types.
In all cases, the size of problem that can be run on a per-processor
basis is limited by 4-byte integer storage to about 2 billion atoms
per processor (2^31), which should not normally be a restriction since
such a problem would have a huge per-processor memory footprint due to
neighbor lists and would run very slowly in terms of CPU
secs/timestep.
:line
2.3 Making LAMMPS with optional packages :h4,link(2_3)
This section has the following sub-sections:
"Package basics"_#2_3_1
"Including/excluding packages"_#2_3_2
"Packages that require extra LAMMPS libraries"_#2_3_3
"Additional Makefile settings for extra libraries"_#2_3_4 :ul
:line
[{Package basics:}] :link(2_3_1)
The source code for LAMMPS is structured as a large set of core files
which are always included, plus optional packages. Packages are
groups of files that enable a specific set of features. For example,
force fields for molecular systems or granular systems are in
packages. You can see the list of all packages by typing "make
package".
The current list of standard packages is as follows:
asphere : aspherical particles and force fields
class2 : class 2 force fields
colloid : colloidal particle force fields
dipole : point dipole particles and force fields
dsmc : Direct Simulation Monte Carlo (DMSC) pair style
gpu : GPU-enabled force field styles
granular : force fields and boundary conditions for granular systems
kspace : long-range Ewald and particle-mesh (PPPM) solvers
manybody : metal, 3-body, bond-order potentials
meam : modified embedded atom method (MEAM) potential
molecule : force fields for molecular systems
opt : optimized versions of a few pair potentials
peri : Peridynamics model and potential
poems : coupled rigid body motion
reax : ReaxFF potential
replica : multi-replica methods
shock : methods for MD simulations of shock loading
srd : stochastic rotation dynamics (SRD)
xtc : dump atom snapshots in XTC format :tb(s=:)
There are also user-contributed packages which may be as simple as a
single additional file or many files grouped together which add a
specific functionality to the code.
The difference between a {standard} package versus a {user} package is
as follows.
Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LAMMPS.
User packages don't necessarily meet these requirements. If you have
problems using a feature provided in a user package, you will likely
need to contact the contributor directly to get help. Information on
how to submit additions you make to LAMMPS as a user-contributed
package is given in "this section"_Section_modify.html#package of the
documentation.
:line
[{Including/excluding packages:}] :link(2_3_2)
Any or all packages can be included or excluded independently BEFORE
LAMMPS is built.
The two exceptions to this are the "gpu" and "opt" packages. Some of
the files in these packages require other packages to also be
included. If this is not the case, then those subsidiary files in
"gpu" and "opt" will not be installed either. To install all the
files in package "gpu", the "asphere" and "kspace" packages must also be
installed. To install all the files in package "opt", the "kspace" and
"manybody" packages must also be installed.
You may wish to exclude certain packages if you will never run certain
kinds of simulations. This will keep you from having to build
auxiliary libraries (see below) and will produce a smaller executable
which may run a bit faster.
By default, LAMMPS includes only the "kspace", "manybody", and
"molecule" packages.
Packages are included or excluded by typing "make yes-name" or "make
no-name", where "name" is the name of the package. You can also type
"make yes-standard", "make no-standard", "make yes-user", "make
no-user", "make yes-all" or "make no-all" to include/exclude various
sets of packages. Type "make package" to see the various options.
IMPORTANT NOTE: These make commands work by simply moving files back
and forth between the main src directory and sub-directories with the
package name, so that the files are seen or not seen when LAMMPS is
built. After you have included or excluded a package, you must
re-build LAMMPS.
Additional make options exist to help manage LAMMPS files that exist
in both the src directory and in package sub-directories. You do not
normally need to use these commands unless you are editing LAMMPS
files or have downloaded a patch from the LAMMPS WWW site.
Typing "make package-update" will overwrite src files with files from
the package directories if the package has been included. It should
be used after a patch is installed, since patches only update the
master package version of a file. Typing "make package-overwrite"
will overwrite files in the package directories with src files.
Typing "make package-check" will list differences between src and
package versions of the same files. Again, type "make package" to see
the various options.
:line
[{Packages that require extra LAMMPS libraries:}] :link(2_3_3)
A few packages (standard or user) require that additional libraries be
compiled first, which LAMMPS will link to when it builds. The source
code for these libraries are included in the LAMMPS distribution under
the "lib" directory. Look at the README files in the lib directories
(e.g. lib/reax/README) for instructions on how to build each library.
IMPORTANT NOTE: If you are including a package in your LAMMPS build
that uses one of these libraries, then you must build the library
BEFORE building LAMMPS itself, since the LAMMPS build will attempt to
link with the library file.
Here is a bit of information about each library:
The "atc" library in lib/atc is used by the user-atc package. It
provides continuum field estimation and molecular dynamics-finite
element coupling methods. It was written primarily by Reese Jones,
Jeremy Templeton and Jonathan Zimmerman at Sandia.
The "gpu" library in lib/gpu is used by the gpu package. It
contains code to enable portions of LAMMPS to run on a GPU chip
associated with your CPU. Currently, only NVIDIA GPUs are supported.
Building this library requires NVIDIA Cuda tools to be installed on
your system. See the "Running on GPUs"_#2_8 section below for more
info about installing and using Cuda.
The "meam" library in lib/meam is used by the meam package.
computes the modified embedded atom method potential, which is a
generalization of EAM potentials that can be used to model a wider
variety of materials. This MEAM implementation was written by Greg
Wagner at Sandia. It requires a F90 compiler to build. The C++ to
FORTRAN function calls in pair_meam.cpp assumes that FORTRAN object
names are converted to C object names by appending an underscore
character. This is generally the case, but on machines that do not
conform to this convention, you will need to modify either the C++
code or your compiler settings.
The "poems" library in lib/poems is used by the poems package.
computes the constrained rigid-body motion of articulated (jointed)
multibody systems. POEMS was written and is distributed by Prof Kurt
Anderson's group at Rensselaer Polytechnic Institute (RPI).
The "reax" library in lib/reax is used by the reax package. It
computes the Reactive Force Field (ReaxFF) potential, developed by
Adri van Duin in Bill Goddard's group at CalTech. This implementation
in LAMMPS uses many of Adri's files and was developed by Aidan
Thompson at Sandia and Hansohl Cho at MIT. It requires a F77 or F90
compiler to build. The C++ to FORTRAN function calls in pair_reax.cpp
assume that FORTRAN object names are converted to C object names by
appending an underscore character. This is generally the case, but on
machines that do not conform to this convention, you will need to
modify either the C++ code or your compiler settings. The name
conversion is handled by the preprocessor macro called FORTRAN in
pair_reax_fortran.h. Different definitions of this macro can be
obtained by adding a machine-specific macro definition to the CCFLAGS
variable in your Makefile e.g. -D_IBM. See pair_reax_fortran.h for
more info.
As described in its README file, each library is built by typing
something like
make -f Makefile.g++ :pre
in the appropriate directory, e.g. in lib/reax.
You must use a Makefile that is a match for your system. If one of
the provided Makefiles is not appropriate for your system you will
need to edit or add one. For example, in the case of Fotran-based
libraries, your system must have a Fortran compiler, the settings for
which will be in the Makefile.
:line
[{Additional Makefile settings for extra libraries:}] :link(2_3_4)
After the desired library or libraries are built, and the package has
been included, you can build LAMMPS itself. For example, from the
lammps/src directory you would type this, to build LAMMPS with ReaxFF.
Note that as discussed in the preceding section, the package library
itself, namely lib/reax/libreax.a, must already have been built, for
the LAMMPS build to be successful.
make yes-reax
make g++ :pre
Also note that simply building the library is not sufficient to use it
from LAMMPS. As in this example, you must also include the package
that uses and wraps the library before you build LAMMPS itself.
As discussed in point (2.4) of "this section"_#2_2_4 above, there are
settings in the low-level Makefile that specify additional system
libraries needed by individual LAMMPS add-on libraries. These are the
settings you must specify correctly in your low-level Makefile in
lammps/src/MAKE, such as Makefile.foo:
To use the gpu package and library, the settings for gpu_SYSLIB and
gpu_SYSPATH must be correct. These are specific to the NVIDIA CUDA
software which must be installed on your system.
To use the meam or reax packages and their libraries which are Fortran
based, the settings for meam_SYSLIB, reax_SYSLIB, meam_SYSPATH, and
reax_SYSPATH must be correct. This is so that the C++ compiler can
perform a cross-language link using the appropriate system Fortran
libraries.
To use the user-atc package and library, the settings for
user-atc_SYSLIB and user-atc_SYSPATH must be correct. This is so that
the appropriate BLAS and LAPACK libs, used by the user-atc library,
can be found.
:line
2.4 Building LAMMPS as a library :h4,link(2_4)
LAMMPS can be built as a library, which can then be called from
another application or a scripting language. See "this
section"_Section_howto.html#4_10 for more info on coupling LAMMPS to
other codes. Building LAMMPS as a library is done by typing
make makelib
make -f Makefile.lib foo :pre
where foo is the machine name. The first "make" command will create a
current Makefile.lib with all the file names in your src dir. The 2nd
"make" command will use it to build LAMMPS as a library. This
requires that Makefile.foo have a library target (lib) and
system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux
for an example. The build will create the file liblmp_foo.a which
another application can link to.
When used from a C++ program, the library allows one or more LAMMPS
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within your application code, as needed.
When used from a C or Fortran program or a scripting language, the
library has a simple function-style interface, provided in
src/library.cpp and src/library.h.
See the sample codes couple/simple/simple.cpp and simple.c as examples
of C++ and C codes that invoke LAMMPS thru its library interface.
There are other examples as well in the couple directory which are
discussed in "this section"_Section_howto.html#4_10 of the manual.
See "this section"_Section_python.html of the manual for a description
of the Python wrapper provided with LAMMPS that operates through the
LAMMPS library interface.
The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See "this section"_Section_howto.html#4_19 of the manual
for a description of the interface and how to extend it for your
needs.
:line
2.5 Running LAMMPS :h4,link(2_5)
By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux
< in.file. This means you first create an input script (e.g. in.file)
containing the desired commands. "This section"_Section_commands.html
describes how input scripts are structured and what commands they
contain.
You can test LAMMPS on any of the sample inputs provided in the
examples or bench directory. Input scripts are named in.* and sample
outputs are named log.*.name.P where name is a machine and P is the
number of processors it was run on.
Here is how you might run a standard Lennard-Jones benchmark on a
Linux box, using mpirun to launch a parallel job:
cd src
make linux
cp lmp_linux ../bench
cd ../bench
mpirun -np 4 lmp_linux < in.lj :pre
See "this page"_bench for timings for this and the other benchmarks
on various platforms.
:link(bench,http://lammps.sandia.gov/bench.html)
:line
On a Windows machine, you can skip making LAMMPS and simply download
an executable. But note that not all packages are available.
The following packages are available: asphere, class2, colloid, dipole,
dsmc, granular, kspace, manybody, molecule, peri, poems, replica, shock,
user-ackland, user-cd-eam, user-cg-cmm, user-ewaldn, user-smd. But these
packages are not available: gpu, meam, opt, reax, xtc, user-atc, user-imd.
To run the LAMMPS executable on a Windows machine, first decide whether
you want to download the non-MPI (serial) or the MPI (parallel) version
of the executable. Download and save the version you have chosen.
For the non-MPI version, follow these steps:
Get a command prompt by going to Start->Run... ,
then typing "cmd". :ulb,l
Move to the directory where you have saved lmp_win_no-mpi.exe
(e.g. by typing: cd "Documents"). :l
At the command prompt, type "lmp_win_no-mpi -in in.lj", replacing in.lj
with the name of your LAMMPS input script. :l,ule
For the MPI version, which allows you to run LAMMPS under Windows on
multiple processors, follow these steps:
Download and install
"MPICH2"_http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads
for Windows. :ulb,l
You'll need to use the mpiexec.exe and smpd.exe files from the MPICH2 package. Put them in
same directory (or path) as the LAMMPS Windows executable. :l
Get a command prompt by going to Start->Run... ,
then typing "cmd". :l
Move to the directory where you have saved lmp_win_mpi.exe
(e.g. by typing: cd "Documents"). :l
Then type something like this: "mpiexec -np 4 -localonly lmp_win_mpi -in in.lj",
replacing in.lj with the name of your LAMMPS input script. :l
Note that you may need to provide smpd with a passphrase --- it doesn't matter what you
type. :l
In this mode, output may not immediately show up on the screen, so
if your input script takes a long time to execute, you may need to be
patient before the output shows up. :l
Alternatively, you can still use this executable to run on a single processor by
typing something like: "lmp_win_mpi -in in.lj". :l,ule
:line
The screen output from LAMMPS is described in the next section. As it
runs, LAMMPS also writes a log.lammps file with the same information.
Note that this sequence of commands copies the LAMMPS executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from (if you launch lmp_linux on its own and not
under mpirun). If that happens, LAMMPS will look for additional input
files and write its output files to the executable directory, rather
than your working directory, which is probably not what you want.
If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See "this section"_Section_errors.html for a
discussion of the various kinds of errors LAMMPS can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
LAMMPS can run a problem on any number of processors, including a
single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories.
LAMMPS can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or setup a smaller problem.
:line
2.6 Command-line options :h4,link(2_6)
At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. Either the full word or the
one-letter abbreviation can be used:
-echo or -e
-partition or -p
-in or -i
-log or -l
-screen or -s
-var or -v :ul
For example, lmp_ibm might be launched as follows:
mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none < in.alloy :pre
Here are the details on the options:
-echo style :pre
Set the style of command echoing. The style can be {none} or {screen}
or {log} or {both}. Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile. This
can be useful to figure out which line of your script is causing an
input error. The default value is {log}. The echo style can also be
set by using the "echo"_echo.html command in the input script itself.
-partition 8x2 4 5 ... :pre
Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P
processors and this switch is not used, LAMMPS runs in one partition,
i.e. all P processors run a single simulation. If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation. The arguments to the switch
specify the number of processors in each partition. Arguments of the
form MxN mean M partitions, each with N processors. Arguments of the
form N mean a single partition with N processors. The sum of
processors in all partitions must equal P. Thus the command
"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
processors.
Note that with MPI installed on a machine (e.g. your desktop), you can
run on more (virtual) processors than you have physical processors.
This can be useful for running "multi-replica
simulations"_Section_howto.html#4_5, on one or a few processors.
The input script specifies what simulation is run on which partition;
see the "variable"_variable.html and "next"_next.html commands. This
"howto section"_Section_howto.html#4_4 gives examples of how to use
these commands in this way. Simulations running on different
partitions can also communicate with each other; see the
"temper"_temper.html command.
-in file :pre
Specify a file to use as an input script. This is an optional switch
when running LAMMPS in one-partition mode. If it is not specified,
LAMMPS reads its input script from stdin - e.g. lmp_linux < in.run.
This is a required switch when running LAMMPS in multi-partition mode,
since multiple processors cannot all read from stdin.
-log file :pre
Specify a log file for LAMMPS to write status information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
file log.lammps. If this switch is used, LAMMPS writes to the
specified file. In multi-partition mode, if the switch is not used, a
log.lammps file is created with hi-level status information. Each
partition also writes to a log.lammps.N file where N is the partition
ID. If the switch is specified in multi-partition mode, the hi-level
logfile is named "file" and each partition also logs information to a
file.N. For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created. Using a
"log"_log.html command in the input script will override this setting.
-screen file :pre
Specify a file for LAMMPS to write its screen information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
screen. If this switch is used, LAMMPS writes to the specified file
instead and you will see no screen output. In multi-partition mode,
if the switch is not used, hi-level status information is written to
the screen. Each partition also writes to a screen.N file where N is
the partition ID. If the switch is specified in multi-partition mode,
the hi-level screen dump is named "file" and each partition also
writes screen information to a file.N. For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed.
-var name value1 value2 ... :pre
Specify a variable that will be defined for substitution purposes when
the input script is read. "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as $\{abc\}). An "index-style
variable"_variable.html will be created and populated with the
subsequent values, e.g. a set of filenames. Using this command-line
option is equivalent to putting the line "variable name index value1
value2 ..." at the beginning of the input script. Defining an index
variable as a command-line argument overrides any setting for the same
index variable in the input script, since index variables cannot be
re-defined. See the "variable"_variable.html command for more info on
defining index and other kinds of variables and "this
section"_Section_commands.html#3_2 for more info on using variables in
input scripts.
:line
2.7 LAMMPS screen output :h4,link(2_7)
As LAMMPS reads an input script, it prints information to both the
screen and a log file about significant actions it takes to setup a
simulation. When the simulation is ready to begin, LAMMPS performs
various initializations and prints the amount of memory (in MBytes per
processor) that the simulation requires. It also prints details of
the initial thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few
timesteps. When the run concludes, LAMMPS prints the final
thermodynamic state and a total run time for the simulation. It then
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:
Loop time of 49.002 on 2 procs for 2004 atoms :pre
Pair time (%) = 35.0495 (71.5267)
Bond time (%) = 0.092046 (0.187841)
Kspce time (%) = 6.42073 (13.103)
Neigh time (%) = 2.73485 (5.5811)
Comm time (%) = 1.50291 (3.06703)
Outpt time (%) = 0.013799 (0.0281601)
Other time (%) = 2.13669 (4.36041) :pre
Nlocal: 1002 ave, 1015 max, 989 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8720 ave, 8724 max, 8716 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354141 ave, 361422 max, 346860 min
Histogram: 1 0 0 0 0 0 0 0 0 1 :pre
Total # of neighbors = 708282
Ave neighs/atom = 353.434
Ave special neighs/atom = 2.34032
Number of reneighborings = 42
Dangerous reneighborings = 2 :pre
The first section gives the breakdown of the CPU run time (in seconds)
into major categories. The second section lists the number of owned
atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
per processor. The max and min values give the spread of these values
across processors with a 10-bin histogram showing the distribution.
The total number of histogram counts is equal to the number of
processors.
The last section gives aggregate statistics for pair-wise neighbors
and special neighbors that LAMMPS keeps track of (see the
"special_bonds"_special_bonds.html command). The number of times
neighbor lists were rebuilt during the run is given as well as the
number of potentially "dangerous" rebuilds. If atom movement
triggered neighbor list rebuilding (see the
"neigh_modify"_neigh_modify.html command), then dangerous
reneighborings are those that were triggered on the first timestep
atom movement was checked for. If this count is non-zero you may wish
to reduce the delay factor to insure no force interactions are missed
by atoms moving beyond the neighbor skin distance before a rebuild
takes place.
If an energy minimization was performed via the
"minimize"_minimize.html command, additional information is printed,
e.g.
Minimization stats:
E initial, next-to-last, final = -0.895962 -2.94193 -2.94342
Gradient 2-norm init/final= 1920.78 20.9992
Gradient inf-norm init/final= 304.283 9.61216
Iterations = 36
Force evaluations = 177 :pre
The first line lists the initial and final energy, as well as the
energy on the next-to-last iteration. The next 2 lines give a measure
of the gradient of the energy (force on all atoms). The 2-norm is the
"length" of this force vector; the inf-norm is the largest component.
The last 2 lines are statistics on how many iterations and
force-evaluations the minimizer required. Multiple force evaluations
are typically done at each iteration to perform a 1d line minimization
in the search direction.
If a "kspace_style"_kspace_style.html long-range Coulombics solve was
performed during the run (PPPM, Ewald), then additional information is
printed, e.g.
FFT time (% of Kspce) = 0.200313 (8.34477)
FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre
The first line gives the time spent doing 3d FFTs (4 per timestep) and
the fraction it represents of the total KSpace time (listed above).
Each 3d FFT requires computation (3 sets of 1d FFTs) and communication
(transposes). The total flops performed is 5Nlog_2(N), where N is the
number of points in the 3d grid. The FFTs are timed with and without
the communication and a Gflop rate is computed. The 3d rate is with
communication; the 1d rate is without (just the 1d FFTs). Thus you
can estimate what fraction of your FFT time was spent in
communication, roughly 75% in the example above.
:line
2.8 Running on GPUs :h4,link(2_8)
A few LAMMPS "pair styles"_pair_style.html can be run on graphical
processing units (GPUs). We plan to add more over time. Currently,
they only support NVIDIA GPU cards. To use them you need to install
certain NVIDIA CUDA software on your system:
Check if you have an NVIDIA card: cat /proc/driver/nvidia/cards/0
Go to http://www.nvidia.com/object/cuda_get.html
Install a driver and toolkit appropriate for your system (SDK is not necessary)
Follow the instructions in README in lammps/lib/gpu to build the library.
Run lammps/lib/gpu/nvc_get_devices to list supported devices and properties :ul
GPU configuration :h4
When using GPUs, you are restricted to one physical GPU per LAMMPS
process. Multiple processes can share a single GPU and in many cases it
will be more efficient to run with multiple processes per GPU. Any GPU
accelerated style requires that "fix gpu"_fix_gpu.html be used in the
input script to select and initialize the GPUs. The format for the fix
is:
fix {name} all gpu {mode} {first} {last} {split} :pre
where {name} is the name for the fix. The gpu fix must be the first
fix specified for a given run, otherwise the program will exit
with an error. The gpu fix will not have any effect on runs
that do not use GPU acceleration; there should be no problem
with specifying the fix first in any input script.
{mode} can be either "force" or "force/neigh". In the former,
neighbor list calculation is performed on the CPU using the
standard LAMMPS routines. In the latter, the neighbor list
calculation is performed on the GPU. The GPU neighbor list
can be used for better performance, however, it
should not be used with a triclinic box.
There are cases when it might be more efficient to select the CPU for neighbor
list builds. If a non-GPU enabled style requires a neighbor list, it will also
be built using CPU routines. Redundant CPU and GPU neighbor list calculations
will typically be less efficient. For "hybrid"_pair_hybrid.html pair
styles, GPU calculated neighbor lists might be less efficient because
no particles will be skipped in a given neighbor list.
{first} is the ID (as reported by lammps/lib/gpu/nvc_get_devices)
of the first GPU that will be used on each node. {last} is the
ID of the last GPU that will be used on each node. If you have
only one GPU per node, {first} and {last} will typically both be
0. Selecting a non-sequential set of GPU IDs (e.g. 0,1,3)
is not currently supported.
{split} is the fraction of particles whose forces, torques,
energies, and/or virials will be calculated on the GPU. This
can be used to perform CPU and GPU force calculations
simultaneously. If {split} is negative, the software will
attempt to calculate the optimal fraction automatically
every 25 timesteps based on CPU and GPU timings. Because the GPU speedups
are dependent on the number of particles, automatic calculation of the
split can be less efficient, but typically results in loop times
within 20% of an optimal fixed split.
If you have two GPUs per node, 8 CPU cores per node, and
would like to run on 4 nodes with dynamic balancing of
force calculation across CPU and GPU cores, the fix
might be
fix 0 all gpu force/neigh 0 1 -1 :pre
with LAMMPS run on 32 processes. In this case, all
CPU cores and GPU devices on the nodes would be utilized.
Each GPU device would be shared by 4 CPU cores. The
CPU cores would perform force calculations for some
fraction of the particles at the same time the GPUs
performed force calculation for the other particles.
Because of the large number of cores on each GPU
device, it might be more efficient to run on fewer
processes per GPU when the number of particles per process
is small (100's of particles); this can be necessary
to keep the GPU cores busy.
GPU input script :h4
In order to use GPU acceleration in LAMMPS,
"fix_gpu"_fix_gpu.html
should be used in order to initialize and configure the
GPUs for use. Additionally, GPU enabled styles must be
selected in the input script. Currently,
this is limited to a few "pair styles"_pair_style.html.
Some GPU-enabled styles have additional restrictions
listed in their documentation.
GPU asynchronous pair computation :h4
The GPU accelerated pair styles can be used to perform
pair style force calculation on the GPU while other
calculations are
performed on the CPU. One method to do this is to specify
a {split} in the gpu fix as described above. In this case,
force calculation for the pair style will also be performed
on the CPU.
When the CPU work in a GPU pair style has finished,
the next force computation will begin, possibly before the
GPU has finished. If {split} is 1.0 in the gpu fix, the next
force computation will begin almost immediately. This can
be used to run a "hybrid"_pair_hybrid.html GPU pair style at
the same time as a hybrid CPU pair style. In this case, the
GPU pair style should be first in the hybrid command in order to
perform simultaneous calculations. This also
allows "bond"_bond_style.html, "angle"_angle_style.html,
"dihedral"_dihedral_style.html, "improper"_improper_style.html,
and "long-range"_kspace_style.html force
computations to be run simultaneously with the GPU pair style.
Once all CPU force computations have completed, the gpu fix
will block until the GPU has finished all work before continuing
the run.
GPU timing :h4
GPU accelerated pair styles can perform computations asynchronously
with CPU computations. The "Pair" time reported by LAMMPS
will be the maximum of the time required to complete the CPU
pair style computations and the time required to complete the GPU
pair style computations. Any time spent for GPU-enabled pair styles
for computations that run simultaneously with "bond"_bond_style.html,
"angle"_angle_style.html, "dihedral"_dihedral_style.html,
"improper"_improper_style.html, and "long-range"_kspace_style.html calculations
will not be included in the "Pair" time.
When {mode} for the gpu fix is force/neigh,
the time for neighbor list calculations on the GPU will be added
into the "Pair" time, not the "Neigh" time. A breakdown of the
times required for various tasks on the GPU (data copy, neighbor
calculations, force computations, etc.) are output only
with the LAMMPS screen output at the end of each run. These timings represent
total time spent on the GPU for each routine, regardless of asynchronous
CPU calculations.
GPU single vs double precision :h4
See the lammps/lib/gpu/README file for instructions on how to build
the LAMMPS gpu library for single, mixed, and double precision. The latter
requires that your GPU card supports double precision.
:line
2.9 Tips for users of previous LAMMPS versions :h4,link(2_9)
The current C++ began with a complete rewrite of LAMMPS 2001, which
was written in F90. Features of earlier versions of LAMMPS are listed
in "this section"_Section_history.html. The F90 and F77 versions
(2001 and 99) are also freely distributed as open-source codes; check
the "LAMMPS WWW Site"_lws for distribution information if you prefer
those versions. The 99 and 2001 versions are no longer under active
development; they do not have all the features of C++ LAMMPS.
If you are a previous user of LAMMPS 2001, these are the most
significant changes you will notice in C++ LAMMPS:
(1) The names and arguments of many input script commands have
changed. All commands are now a single word (e.g. read_data instead
of read data).
(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS,
but you may need to specify the relevant commands in different ways.
(3) The format of the data file can be streamlined for some problems.
See the "read_data"_read_data.html command for details. The data file
section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS.
(4) Binary restart files written by LAMMPS 2001 cannot be read by C++
LAMMPS with a "read_restart"_read_restart.html command. This is
because they were output by F90 which writes in a different binary
format than C or C++ writes or reads. Use the {restart2data} tool
provided with LAMMPS 2001 to convert the 2001 restart file to a text
data file. Then edit the data file as necessary before using the C++
LAMMPS "read_data"_read_data.html command to read it in.
(5) There are numerous small numerical changes in C++ LAMMPS that mean
you will not get identical answers when comparing to a 2001 run.
However, your initial thermodynamic energy and MD trajectory should be
close if you have setup the problem for both codes the same.
diff --git a/doc/compute_pair_local.html b/doc/compute_pair_local.html
index 0fe54e113..f6bea11ce 100644
--- a/doc/compute_pair_local.html
+++ b/doc/compute_pair_local.html
@@ -1,90 +1,100 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>compute pair/local command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID group-ID pair/local input1 input2 ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command
<LI>pair/local = style name of this compute command
<LI>zero or more keywords may be appended
<LI>keyword = <I>dist</I> or <I>eng</I> or <I>force</I>
<PRE> <I>dist</I> = tabulate pairwise distances
<I>eng</I> = tablutate pairwise energies
<I>force</I> = tablutate pairwise forces
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 all pair/local eng
compute 1 all pair/local dist eng force
</PRE>
<P><B>Description:</B>
</P>
<P>Define a computation that calculates properties of individual pairwise
interactions. The number of datums generated, aggregated across all
processors, equals the number of pairwise interactions in the system.
</P>
<P>The local data stored by this command is generated by looping over the
pairwise neighbor list. Info about an individual pairwise interaction
will only be included if both atoms in the pair are in the specified
compute group, and if the current pairwise distance is less than the
force cutoff distance for that interaction, as defined by the
<A HREF = "pair_style.html">pair_style</A> and <A HREF = "pair_coeff.html">pair_coeff</A>
commands.
</P>
<P>The output <I>dist</I> will be in distance <A HREF = "units.html">units</A>. The output
<I>eng</I> will be in energy <A HREF = "units.html">units</A>. The output <I>force</I> will
be in force <A HREF = "units.html">units</A>.
</P>
<P>Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, pair output from the <A HREF = "compute_property_local.html">compute
property/local</A> command can be combined
with data from this command and output by the <A HREF = "dump.html">dump local</A>
command in a consistent way.
</P>
+<P>IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
+1-4 interactions within the molecular topology, their pairwise
+interaction may be turned off, and thus they may not appear in the
+neighbor list, and will not be part of the local data created by this
+command. More specifically, this may be true of I,J pairs with a
+weighting factor of 0.0; pairs with a non-zero weighting factor are
+included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
+interactions are set by the <A HREF = "special_bonds.html">special_bonds</A>
+command.
+</P>
<P><B>Output info:</B>
</P>
<P>This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of pairs. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See <A HREF = "Section_howto.html#4_15">this
section</A> for an overview of LAMMPS output
options.
</P>
<P>The output for <I>dist</I> will be in distance <A HREF = "units.html">units</A>. The
output for <I>eng</I> will be in energy <A HREF = "units.html">units</A>. The output for
<I>force</I> will be in force <A HREF = "units.html">units</A>.
</P>
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "dump.html">dump local</A>, <A HREF = "compute_property_local.html">compute
property/local</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/compute_pair_local.txt b/doc/compute_pair_local.txt
index 9caefb5e1..0659e8082 100644
--- a/doc/compute_pair_local.txt
+++ b/doc/compute_pair_local.txt
@@ -1,80 +1,90 @@
"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
compute pair/local command :h3
[Syntax:]
compute ID group-ID pair/local input1 input2 ... :pre
ID, group-ID are documented in "compute"_compute.html command :ulb,l
pair/local = style name of this compute command :l
zero or more keywords may be appended :l
keyword = {dist} or {eng} or {force} :l
{dist} = tabulate pairwise distances
{eng} = tablutate pairwise energies
{force} = tablutate pairwise forces :pre
:ule
[Examples:]
compute 1 all pair/local eng
compute 1 all pair/local dist eng force :pre
[Description:]
Define a computation that calculates properties of individual pairwise
interactions. The number of datums generated, aggregated across all
processors, equals the number of pairwise interactions in the system.
The local data stored by this command is generated by looping over the
pairwise neighbor list. Info about an individual pairwise interaction
will only be included if both atoms in the pair are in the specified
compute group, and if the current pairwise distance is less than the
force cutoff distance for that interaction, as defined by the
"pair_style"_pair_style.html and "pair_coeff"_pair_coeff.html
commands.
The output {dist} will be in distance "units"_units.html. The output
{eng} will be in energy "units"_units.html. The output {force} will
be in force "units"_units.html.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, pair output from the "compute
property/local"_compute_property_local.html command can be combined
with data from this command and output by the "dump local"_dump.html
command in a consistent way.
+IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
+1-4 interactions within the molecular topology, their pairwise
+interaction may be turned off, and thus they may not appear in the
+neighbor list, and will not be part of the local data created by this
+command. More specifically, this may be true of I,J pairs with a
+weighting factor of 0.0; pairs with a non-zero weighting factor are
+included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
+interactions are set by the "special_bonds"_special_bonds.html
+command.
+
[Output info:]
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of pairs. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See "this
section"_Section_howto.html#4_15 for an overview of LAMMPS output
options.
The output for {dist} will be in distance "units"_units.html. The
output for {eng} will be in energy "units"_units.html. The output for
{force} will be in force "units"_units.html.
[Restrictions:] none
[Related commands:]
"dump local"_dump.html, "compute
property/local"_compute_property_local.html
[Default:] none
diff --git a/doc/compute_property_local.html b/doc/compute_property_local.html
index 9583f4749..546ff6ff5 100644
--- a/doc/compute_property_local.html
+++ b/doc/compute_property_local.html
@@ -1,137 +1,137 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>compute property/local command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID group-ID property/local input1 input2 ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command
<LI>property/local = style name of this compute command
<LI>input = one or more attributes
<PRE> possible attributes = natom1 natom2
patom1 patom2
batom1 batom2 btype
aatom1 aatom2 aatom3 atype
datom1 datom2 datom3 dtype
iatom1 iatom2 iatom3 itype
</PRE>
<PRE> natom1, natom2 = IDs of 2 atoms in each pair (within neighbor cutoff)
patom1, patom2 = IDs of 2 atoms in each pair (within force cutoff)
batom1, batom2 = IDs of 2 atoms in each bond
btype = bond type of each bond
aatom1, aatom2, aatom3 = IDs of 3 atoms in each angle
atype = angle type of each angle
datom1, datom2, datom3, datom4 = IDs of 4 atoms in each dihedral
dtype = dihedral type of each dihedral
iatom1, iatom2, iatom3, iatom4 = IDs of 4 atoms in each improper
itype = improper type of each improper
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 all property/local btype batom1 batom2
compute 1 all property/local atype aatom2
</PRE>
<P><B>Description:</B>
</P>
<P>Define a computation that stores the specified attributes as local
data so it can be accessed by other <A HREF = "Section_howto.html#4_15">output
commands</A>. If the input attributes refer to
bond information, then the number of datums generated, aggregated
across all processors, equals the number of bonds in the system.
Ditto for pairs, angles, etc.
</P>
<P>If multiple input attributes are specified then they must all generate
the same amount of information, so that the resulting local array has
the same number of rows for each column. This means that only bond
attributes can be specified together, or angle attributes, etc. Bond
and angle attributes can not be mixed in the same compute
property/local command.
</P>
<P>If the inputs are pair attributes, the local data is generated by
looping over the pairwise neighbor list. Info about an individual
pairwise interaction will only be included if both atoms in the pair
are in the specified compute group. For <I>natom1</I> and <I>natom2</I>, all
atom pairs in the neighbor list are considered (out to the neighbor
cutoff = force cutoff + <A HREF = "neighbor.html">neighbor skin</A>). For <I>patom1</I>
and <I>patom2</I>, the distance between the atoms must be less than the
force cutoff distance for that pair to be included, as defined by the
<A HREF = "pair_style.html">pair_style</A> and <A HREF = "pair_coeff.html">pair_coeff</A>
commands.
</P>
<P>If the inputs are bond, angle, etc attributes, the local data is
generated by looping over all the atoms owned on a processor and
extracting bond, angle, etc info. For bonds, info about an individual
bond will only be included if both atoms in the bond are in the
specified compute group. Likewise for angles, dihedrals, etc.
</P>
<P>Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, output from the <A HREF = "compute_bond_local.html">compute
bond/local</A> command can be combined with bond
atom indices from this command and output by the <A HREF = "dump.html">dump
local</A> command in a consistent way.
</P>
<P>The <I>natom1</I> and <I>natom2</I>, or <I>patom1</I> and <I>patom2</I> attributes refer
to the atom IDs of the 2 atoms in each pairwise interaction computed
by the <A HREF = "pair_style.html">pair_style</A> command.
</P>
<P>IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
1-4 interactions within the molecular topology, their pairwise
-interaction may be turned off, and thus they will not appear in the
+interaction may be turned off, and thus they may not appear in the
neighbor list, and will not be part of the local data created by this
-command. More specifically, this is true of I,J pairs with a
+command. More specifically, this may be true of I,J pairs with a
weighting factor of 0.0; pairs with a non-zero weighting factor are
included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
interactions are set by the <A HREF = "special_bonds.html">special_bonds</A>
command.
</P>
<P>The <I>batom1</I> and <I>batom2</I> attributes refer to the atom IDs of the 2
atoms in each <A HREF = "bond_style.html">bond</A>. The <I>btype</I> attribute refers to
the type of the bond, from 1 to Nbtypes = # of bond types. The number
of bond types is defined in the data file read by the
<A HREF = "read_data.html">read_data</A> command. The attributes that start with
"a", "d", "i", refer to similar values for <A HREF = "angle_style.html">angles</A>,
<A HREF = "dihedral_style.html">dihedrals</A>, and <A HREF = "improper_style.html">impropers</A>.
</P>
<P><B>Output info:</B>
</P>
<P>This compute calculates a local vector or local array depending on the
number of input values. The length of the vector or number of rows in
the array is the number of bonds, angles, etc. If a single input is
specified, a local vector is produced. If two or more inputs are
specified, a local array is produced where the number of columns = the
number of inputs. The vector or array can be accessed by any command
that uses local values from a compute as input. See <A HREF = "Section_howto.html#4_15">this
section</A> for an overview of LAMMPS output
options.
</P>
<P>The vector or array values will be integers that correspond to the
specified attribute.
</P>
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "dump.html">dump local</A>, <A HREF = "compute_reduce.html">compute reduce</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/compute_property_local.txt b/doc/compute_property_local.txt
index 1baaedd06..1f3726b43 100644
--- a/doc/compute_property_local.txt
+++ b/doc/compute_property_local.txt
@@ -1,128 +1,128 @@
"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
compute property/local command :h3
[Syntax:]
compute ID group-ID property/local input1 input2 ... :pre
ID, group-ID are documented in "compute"_compute.html command :ulb,l
property/local = style name of this compute command :l
input = one or more attributes :l
possible attributes = natom1 natom2
patom1 patom2
batom1 batom2 btype
aatom1 aatom2 aatom3 atype
datom1 datom2 datom3 dtype
iatom1 iatom2 iatom3 itype :pre
natom1, natom2 = IDs of 2 atoms in each pair (within neighbor cutoff)
patom1, patom2 = IDs of 2 atoms in each pair (within force cutoff)
batom1, batom2 = IDs of 2 atoms in each bond
btype = bond type of each bond
aatom1, aatom2, aatom3 = IDs of 3 atoms in each angle
atype = angle type of each angle
datom1, datom2, datom3, datom4 = IDs of 4 atoms in each dihedral
dtype = dihedral type of each dihedral
iatom1, iatom2, iatom3, iatom4 = IDs of 4 atoms in each improper
itype = improper type of each improper :pre
:ule
[Examples:]
compute 1 all property/local btype batom1 batom2
compute 1 all property/local atype aatom2 :pre
[Description:]
Define a computation that stores the specified attributes as local
data so it can be accessed by other "output
commands"_Section_howto.html#4_15. If the input attributes refer to
bond information, then the number of datums generated, aggregated
across all processors, equals the number of bonds in the system.
Ditto for pairs, angles, etc.
If multiple input attributes are specified then they must all generate
the same amount of information, so that the resulting local array has
the same number of rows for each column. This means that only bond
attributes can be specified together, or angle attributes, etc. Bond
and angle attributes can not be mixed in the same compute
property/local command.
If the inputs are pair attributes, the local data is generated by
looping over the pairwise neighbor list. Info about an individual
pairwise interaction will only be included if both atoms in the pair
are in the specified compute group. For {natom1} and {natom2}, all
atom pairs in the neighbor list are considered (out to the neighbor
cutoff = force cutoff + "neighbor skin"_neighbor.html). For {patom1}
and {patom2}, the distance between the atoms must be less than the
force cutoff distance for that pair to be included, as defined by the
"pair_style"_pair_style.html and "pair_coeff"_pair_coeff.html
commands.
If the inputs are bond, angle, etc attributes, the local data is
generated by looping over all the atoms owned on a processor and
extracting bond, angle, etc info. For bonds, info about an individual
bond will only be included if both atoms in the bond are in the
specified compute group. Likewise for angles, dihedrals, etc.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, output from the "compute
bond/local"_compute_bond_local.html command can be combined with bond
atom indices from this command and output by the "dump
local"_dump.html command in a consistent way.
The {natom1} and {natom2}, or {patom1} and {patom2} attributes refer
to the atom IDs of the 2 atoms in each pairwise interaction computed
by the "pair_style"_pair_style.html command.
IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
1-4 interactions within the molecular topology, their pairwise
-interaction may be turned off, and thus they will not appear in the
+interaction may be turned off, and thus they may not appear in the
neighbor list, and will not be part of the local data created by this
-command. More specifically, this is true of I,J pairs with a
+command. More specifically, this may be true of I,J pairs with a
weighting factor of 0.0; pairs with a non-zero weighting factor are
included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
interactions are set by the "special_bonds"_special_bonds.html
command.
The {batom1} and {batom2} attributes refer to the atom IDs of the 2
atoms in each "bond"_bond_style.html. The {btype} attribute refers to
the type of the bond, from 1 to Nbtypes = # of bond types. The number
of bond types is defined in the data file read by the
"read_data"_read_data.html command. The attributes that start with
"a", "d", "i", refer to similar values for "angles"_angle_style.html,
"dihedrals"_dihedral_style.html, and "impropers"_improper_style.html.
[Output info:]
This compute calculates a local vector or local array depending on the
number of input values. The length of the vector or number of rows in
the array is the number of bonds, angles, etc. If a single input is
specified, a local vector is produced. If two or more inputs are
specified, a local array is produced where the number of columns = the
number of inputs. The vector or array can be accessed by any command
that uses local values from a compute as input. See "this
section"_Section_howto.html#4_15 for an overview of LAMMPS output
options.
The vector or array values will be integers that correspond to the
specified attribute.
[Restrictions:] none
[Related commands:]
"dump local"_dump.html, "compute reduce"_compute_reduce.html
[Default:] none
diff --git a/doc/compute_rdf.html b/doc/compute_rdf.html
index a6ded207c..dd93bfd8f 100644
--- a/doc/compute_rdf.html
+++ b/doc/compute_rdf.html
@@ -1,141 +1,130 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>compute rdf command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID group-ID rdf Nbin itype1 jtype1 itype2 jtype2 ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command
<LI>rdf = style name of this compute command
<LI>Nbin = number of RDF bins
<LI>itypeN = central atom type for Nth RDF histogram (see asterisk form below)
<LI>jtypeN = distribution atom type for Nth RDF histogram (see asterisk form below)
</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 all rdf 100
compute 1 all rdf 100 1 1
compute 1 all rdf 100 * 3
compute 1 fluid rdf 500 1 1 1 2 2 1 2 2
compute 1 fluid rdf 500 1*3 2 5 *10
</PRE>
<P><B>Description:</B>
</P>
<P>Define a computation that calculates the radial distribution function
(RDF), also called g(r), and the coordination number for a group of
particles. Both are calculated in histogram form by binning pairwise
distances into <I>Nbin</I> bins from 0.0 to the maximum force cutoff
defined by the <A HREF = "pair_style.html">pair_style</A> command. The bins are of
uniform size in radial distance. Thus a single bin encompasses a thin
shell of distances in 3d and a thin ring of distances in 2d.
</P>
<P>The <I>itypeN</I> and <I>jtypeN</I> arguments are optional. These arguments
must come in pairs. If no pairs are listed, then a single histogram
is computed for g(r) between all atom types. If one or more pairs are
listed, then a separate histogram is generated for each
<I>itype</I>,<I>jtype</I> pair.
</P>
<P>The <I>itypeN</I> and <I>jtypeN</I> settings can be specified in one of two
ways. An explicit numeric value can be used, as in the 4th example
above. Or a wild-card asterisk can be used to specify a range of atom
types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
number of atom types, then an asterisk with no numeric values means
all types from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
</P>
<P>If both <I>itypeN</I> and <I>jtypeN</I> are single values, as in the 4th example
above, this means that a g(r) is computed where atoms of type <I>itypeN</I>
are the central atom, and atoms of type <I>jtypeN</I> are the distribution
atom. If either <I>itypeN</I> and <I>jtypeN</I> represent a range of values via
the wild-card asterisk, as in the 5th example above, this means that a
g(r) is computed where atoms of any of the range of types represented
by <I>itypeN</I> are the central atom, and atoms of any of the range of
types represented by <I>jtypeN</I> are the distribution atom.
</P>
<P>Pairwise distances are generated by looping over a pairwise neighbor
list, just as they would be in a <A HREF = "pair_style.html">pair_style</A>
computation. The distance between two atoms I and J is included in
a specific histogram if the following criteria are met:
</P>
<UL><LI>atoms I,J are both in the specified compute group
<LI>the distance between atoms I,J is less than the maximum force cutoff
<LI>the type of the I atom matches itypeN (one or a range of types)
-<LI>the type of the J atom matches jtypeN (one or a range of types)
-<LI>the I,J interaction is included in the neighbor list
+<LI>the type of the J atom matches jtypeN (one or a range of types)
</UL>
-<P>IMPORTANT NOTE: The last point is relevant for molecular systems with
-bonds, because if two atoms I,J are involved in 1-2, 1-3, 1-4
-interactions within the molecular topology, their pairwise interaction
-may be turned off, and thus they will not appear in the neighbor list,
-and will not contribute to g(r). More specifically, this is true of
-I,J pairs with a weighting factor of 0.0; pairs with a non-zero
-weighting factor are included. The weighting factors for 1-2, 1-3,
-and 1-4 pairwise interactions are set by the
-<A HREF = "special_bonds.html">special_bonds</A> command.
-</P>
<P>It is OK if a particular pairwise distance is included in more than
one individual histogram, due to the way the <I>itypeN</I> and <I>jtypeN</I>
arguments are specified.
</P>
<P>The g(r) value for a bin is calculated from the histogram count by
scaling it by the idealized number of how many counts there would be
if atoms of type <I>jtypeN</I> were uniformly distributed. Thus it
involves the count of <I>itypeN</I> atoms, the count of <I>jtypeN</I> atoms, the
volume of the entire simulation box, and the volume of the bin's thin
shell in 3d (or the area of the bin's thin ring in 2d).
</P>
<P>A coordination number coord(r) is also calculated, which is the sum of
g(r) values for all bins up to and including the current bin.
</P>
<P>The simplest way to output the results of the compute rdf calculation
to a file is to use the <A HREF = "fix_ave_time.html">fix ave/time</A> command, for
example:
</P>
<PRE>compute myRDF all rdf 50
fix 1 all ave/time 100 1 100 c_myRDF file tmp.rdf mode vector
</PRE>
<P><B>Output info:</B>
</P>
<P>This compute calculates a global array with the number of rows =
<I>Nbins</I>, and the number of columns = 1 + 2*Npairs, where Npairs is the
number of I,J pairings specified. The first column has the bin
coordinate (center of the bin), Each successive set of 2 columns has
the g(r) and coord(r) values for a specific set of <I>itypeN</I> versus
<I>jtypeN</I> interactions, as described above. These values can be used
by any command that uses a global values from a compute as input. See
<A HREF = "Section_howto.html#4_15">this section</A> for an overview of LAMMPS
output options.
</P>
<P>The array values calculated by this compute are all "intensive".
</P>
<P>The first column of array values will be in distance
<A HREF = "units.html">units</A>. The g(r) columns of array values are normalized
numbers >= 0.0. The coordination number columns of array values are
also numbers >= 0.0.
</P>
<P><B>Restrictions:</B>
</P>
<P>The RDF is not computed for distances longer than the force cutoff,
since processors (in parallel) don't know about atom coordinates for
atoms further away than that distance. If you want an RDF for larger
distances, you'll need to post-process a dump file.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "fix_ave_time.html">fix ave/time</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/compute_rdf.txt b/doc/compute_rdf.txt
index 595087af0..a4ddf137d 100644
--- a/doc/compute_rdf.txt
+++ b/doc/compute_rdf.txt
@@ -1,136 +1,125 @@
"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
compute rdf command :h3
[Syntax:]
compute ID group-ID rdf Nbin itype1 jtype1 itype2 jtype2 ... :pre
ID, group-ID are documented in "compute"_compute.html command
rdf = style name of this compute command
Nbin = number of RDF bins
itypeN = central atom type for Nth RDF histogram (see asterisk form below)
jtypeN = distribution atom type for Nth RDF histogram (see asterisk form below) :ul
[Examples:]
compute 1 all rdf 100
compute 1 all rdf 100 1 1
compute 1 all rdf 100 * 3
compute 1 fluid rdf 500 1 1 1 2 2 1 2 2
compute 1 fluid rdf 500 1*3 2 5 *10 :pre
[Description:]
Define a computation that calculates the radial distribution function
(RDF), also called g(r), and the coordination number for a group of
particles. Both are calculated in histogram form by binning pairwise
distances into {Nbin} bins from 0.0 to the maximum force cutoff
defined by the "pair_style"_pair_style.html command. The bins are of
uniform size in radial distance. Thus a single bin encompasses a thin
shell of distances in 3d and a thin ring of distances in 2d.
The {itypeN} and {jtypeN} arguments are optional. These arguments
must come in pairs. If no pairs are listed, then a single histogram
is computed for g(r) between all atom types. If one or more pairs are
listed, then a separate histogram is generated for each
{itype},{jtype} pair.
The {itypeN} and {jtypeN} settings can be specified in one of two
ways. An explicit numeric value can be used, as in the 4th example
above. Or a wild-card asterisk can be used to specify a range of atom
types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
number of atom types, then an asterisk with no numeric values means
all types from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
If both {itypeN} and {jtypeN} are single values, as in the 4th example
above, this means that a g(r) is computed where atoms of type {itypeN}
are the central atom, and atoms of type {jtypeN} are the distribution
atom. If either {itypeN} and {jtypeN} represent a range of values via
the wild-card asterisk, as in the 5th example above, this means that a
g(r) is computed where atoms of any of the range of types represented
by {itypeN} are the central atom, and atoms of any of the range of
types represented by {jtypeN} are the distribution atom.
Pairwise distances are generated by looping over a pairwise neighbor
list, just as they would be in a "pair_style"_pair_style.html
computation. The distance between two atoms I and J is included in
a specific histogram if the following criteria are met:
atoms I,J are both in the specified compute group
the distance between atoms I,J is less than the maximum force cutoff
the type of the I atom matches itypeN (one or a range of types)
-the type of the J atom matches jtypeN (one or a range of types)
-the I,J interaction is included in the neighbor list :ul
-
-IMPORTANT NOTE: The last point is relevant for molecular systems with
-bonds, because if two atoms I,J are involved in 1-2, 1-3, 1-4
-interactions within the molecular topology, their pairwise interaction
-may be turned off, and thus they will not appear in the neighbor list,
-and will not contribute to g(r). More specifically, this is true of
-I,J pairs with a weighting factor of 0.0; pairs with a non-zero
-weighting factor are included. The weighting factors for 1-2, 1-3,
-and 1-4 pairwise interactions are set by the
-"special_bonds"_special_bonds.html command.
+the type of the J atom matches jtypeN (one or a range of types) :ul
It is OK if a particular pairwise distance is included in more than
one individual histogram, due to the way the {itypeN} and {jtypeN}
arguments are specified.
The g(r) value for a bin is calculated from the histogram count by
scaling it by the idealized number of how many counts there would be
if atoms of type {jtypeN} were uniformly distributed. Thus it
involves the count of {itypeN} atoms, the count of {jtypeN} atoms, the
volume of the entire simulation box, and the volume of the bin's thin
shell in 3d (or the area of the bin's thin ring in 2d).
A coordination number coord(r) is also calculated, which is the sum of
g(r) values for all bins up to and including the current bin.
The simplest way to output the results of the compute rdf calculation
to a file is to use the "fix ave/time"_fix_ave_time.html command, for
example:
compute myRDF all rdf 50
fix 1 all ave/time 100 1 100 c_myRDF file tmp.rdf mode vector :pre
[Output info:]
This compute calculates a global array with the number of rows =
{Nbins}, and the number of columns = 1 + 2*Npairs, where Npairs is the
number of I,J pairings specified. The first column has the bin
coordinate (center of the bin), Each successive set of 2 columns has
the g(r) and coord(r) values for a specific set of {itypeN} versus
{jtypeN} interactions, as described above. These values can be used
by any command that uses a global values from a compute as input. See
"this section"_Section_howto.html#4_15 for an overview of LAMMPS
output options.
The array values calculated by this compute are all "intensive".
The first column of array values will be in distance
"units"_units.html. The g(r) columns of array values are normalized
numbers >= 0.0. The coordination number columns of array values are
also numbers >= 0.0.
[Restrictions:]
The RDF is not computed for distances longer than the force cutoff,
since processors (in parallel) don't know about atom coordinates for
atoms further away than that distance. If you want an RDF for larger
distances, you'll need to post-process a dump file.
[Related commands:]
"fix ave/time"_fix_ave_time.html
[Default:] none
diff --git a/doc/dump.html b/doc/dump.html
index fad0888e9..0dd5e729d 100644
--- a/doc/dump.html
+++ b/doc/dump.html
@@ -1,497 +1,519 @@
<HTML>
<CENTER> <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>dump command
</H3>
+<H3><A HREF = "dump_image.html">dump image</A> command
+</H3>
<P><B>Syntax:</B>
</P>
<PRE>dump ID group-ID style N file args
</PRE>
<UL><LI>ID = user-assigned name for the dump
<LI>group-ID = ID of the group of atoms to be dumped
-<LI>style = <I>atom</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>local</I> or <I>custom</I>
+<LI>style = <I>atom</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>image</I> or <I>local</I> or <I>custom</I>
<LI>N = dump every this many timesteps
<LI>file = name of file to write dump info to
<LI>args = list of arguments for a particular style
<PRE> <I>atom</I> args = none
<I>cfg</I> args = same as <I>custom</I> args, see below
<I>dcd</I> args = none
<I>xtc</I> args = none
<I>xyz</I> args = none
</PRE>
+<PRE> <I>image</I> args = discussed on <A HREF = "dump_image.html">dump image</A> doc page
+</PRE>
<PRE> <I>local</I> args = list of local attributes
possible attributes = index, c_ID, c_ID[N], f_ID, f_ID[N]
index = enumeration of local values
c_ID = local vector calculated by a compute with ID
c_ID[N] = Nth column of local array calculated by a compute with ID
f_ID = local vector calculated by a fix with ID
f_ID[N] = Nth column of local array calculated by a fix with ID
</PRE>
<PRE> <I>custom</I> args = list of atom attributes
possible attributes = id, mol, type, mass,
x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz,
radius, omegax, omegay, omegaz,
angmomx, angmomy, angmomz,
quatw, quati, quatj, quatk, tqx, tqy, tqz,
spin, eradius, ervel, erforce,
c_ID, c_ID[N], f_ID, f_ID[N], v_name
</PRE>
<PRE> id = atom ID
mol = molecule ID
type = atom type
mass = atom mass
x,y,z = unscaled atom coordinates
xs,ys,zs = scaled atom coordinates
xu,yu,zu = unwrapped atom coordinates
ix,iy,iz = box image that the atom is in
vx,vy,vz = atom velocities
fx,fy,fz = forces on atoms
q = atom charge
mux,muy,muz = orientation of dipolar atom
radius = radius of extended spherical particle
omegax,omegay,omegaz = angular velocity of extended particle
angmomx,angmomy,angmomz = angular momentum of extended particle
quatw,quati,quatj,quatk = quaternion components for aspherical particles
tqx,tqy,tqz = torque on extended particles
spin = electron spin
eradius = electron radius
ervel = electron radial velocity
erforce = electron radial force
c_ID = per-atom vector calculated by a compute with ID
c_ID[N] = Nth column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[N] = Nth column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>dump myDump all atom 100 dump.atom
dump 2 subgroup atom 50 dump.run.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
dump 2 inner cfg 10 dump.snap.*.cfg id type xs ys zs vx vy vz
dump snap all cfg 100 dump.config.*.cfg id type xs ys zs id type c_Stress<B>2</B>
dump 1 all xtc 1000 file.xtc
dump e_data all custom 100 dump.eff id type x y z spin eradius fx fy fz eforce
</PRE>
<P><B>Description:</B>
</P>
<P>Dump a snapshot of atom quantities to one or more files every N
-timesteps in one of several styles. As described below, the filename
-determines the kind of output (text or binary or gzipped, one big file
-or one per timestep, one big file or one per processor). Only
-information for atoms in the specified group is dumped. The
-<A HREF = "dump_modify.html">dump_modify</A> command can also alter what atoms are
-included. Not all styles support all these options; see details
-below.
+timesteps in one of several styles. The <I>image</I> style is the
+exception; it creates a JPG or PPM image file of the atom
+configuration every N timesteps, as discussed on the <A HREF = "dump_image.html">dump
+image</A> doc page.
+</P>
+<P>Only information for atoms in the specified group is dumped. The
+<A HREF = "dump_modify.html">dump_modify thresh and region</A> commands can also
+alter what atoms are included. Not all styles support all these
+options; see details below.
+</P>
+<P>As described below, the filename determines the kind of output (text
+or binary or gzipped, one big file or one per timestep, one big file
+or one per processor).
</P>
<P>IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom written to a dump file may be slightly outside the simulation
box.
</P>
<P>IMPORTANT NOTE: Unless the <A HREF = "dump_modify.html">dump_modify sort</A> option
is invoked, the lines of atom information written to dump files
(typically one line per atom) will be in an indeterminate order for
each snapshot. This is even true when running on a single processor,
if the <A HREF = "atom_modify.html">atom_modify sort</A> option is on, which it is
by default. In this case atoms are re-ordered periodically during a
simulation, due to spatial sorting. It is also true when running in
parallel, because data for a single snapshot is collected from
multiple processors.
</P>
<P>For the <I>atom</I>, <I>custom</I>, <I>cfg</I>, and <I>local</I> styles, sorting is off by
default. For the <I>dcd</I>, <I>xtc</I>, and <I>xyz</I> styles, sorting by atom ID
is on by default. See the <A HREF = "dump_modify.html">dump_modify</A> doc page for
details.
</P>
<HR>
<P>The <I>style</I> keyword determines what atom quantities are written to the
file and in what format. Settings made via the
<A HREF = "dump_modify.html">dump_modify</A> command can also alter the format of
individual values and the file itself.
</P>
<P>The <I>atom</I>, <I>local</I>, and <I>custom</I> styles create files in a simple text
format that is self-explanatory when viewing a dump file. Many of the
LAMMPS <A HREF = "Section_tools.html">post-processing tools</A>, including
<A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A>, work with
this format.
</P>
<P>For post-processing purposes the <I>atom</I> and <I>custom</I> text files are
self-describing in the following sense.
</P>
<P>The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:
</P>
-<PRE>ITEM: BOX BOUNDS
+<PRE>ITEM: BOX BOUNDS xx yy zz
xlo xhi
ylo yhi
zlo zhi
</PRE>
<P>where xlo,xhi are the maximum extents of the simulation box in the
-x-dimension, and similarly for y and z.
+x-dimension, and similarly for y and z. The "xx yy zz" represent 6
+characters that encode the style of boundary for each of the 6
+simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each
+flag is either p = periodic, f = fixed, s = shrink wrap, or m = shrink
+wrapped with a minimum value. See the <A HREF = "doc/boundary.html">boundary</A>
+command for details.
</P>
<P>For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
formatted as follows:
</P>
-<PRE>ITEM: BOX BOUNDS xy xz yz
+<PRE>ITEM: BOX BOUNDS xx yy zz xy xz yz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz
</PRE>
<P>This bounding box is convenient for many visualization programs.
</P>
<P>See <A HREF = "Section_howto.html#4_12">this section</A> of the doc pages for a
geometric description of triclinic boxes, as defined by LAMMPS, simple
formulas for how the 6 bounding box extents (xlo_bound,xhi_bound,etc)
are calculated from the triclinic parameters, and how to transform
those parameters to and from other commonly used triclinic
representations.
</P>
<P>The "ITEM: ATOMS" line in each snapshot lists column descriptors for
the per-atom lines that follow. For example, the descriptors would be
"id type xs ys zs" for the default <I>atom</I> style, and would be the atom
attributes you specify in the dump command for the <I>custom</I> style.
</P>
<P>For style <I>atom</I>, atom coordinates are written to the file, along with
the atom ID and atom type. By default, atom coords are written in a
scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom
is at a location 1/4 of the distance from xlo to xhi of the box
boundaries. The format can be changed to unscaled coords via the
<A HREF = "dump_modify.html">dump_modify</A> settings. Image flags can also be
added for each atom via dump_modify.
</P>
<P>Style <I>custom</I> allows you to specify a list of atom attributes to be
written to the dump file for each atom. Possible attributes are
listed above and will appear in the order specified. You cannot
specify a quantity that is not defined for a particular simulation -
such as <I>q</I> for atom style <I>bond</I>, since that atom style doesn't
assign charges. Dumps occur at the very end of a timestep, so atom
attributes will include effects due to fixes that are applied during
the timestep. An explanation of the possible dump custom attributes
is given below.
</P>
<P>For style <I>local</I>, local output generated by <A HREF = "compute.html">computes</A>
and <A HREF = "fix.html">fixes</A> is used to gnerate lines of output that is
written to the dump file. This local data is typically calculated by
each processor based on the atoms it owns, but there may be zero or
more entities per atom, e.g. a list of bond distances. An explanation
of the possible dump local attributes is given below. Note that by
using input from the <A HREF = "compute_property_local.html">compute
property/local</A> command with dump local,
it is possible to generate information on bonds, angles, etc that can
be cut and pasted directly into a data file read by the
<A HREF = "read_data.html">read_data</A> command.
</P>
<P>Style <I>cfg</I> has the same command syntax as style <I>custom</I> and writes
extended CFG format files, as used by the
<A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> visualization
package. Since the extended CFG format uses a single snapshot of the
system per file, a wildcard "*" must be included in the filename, as
discussed below. The list of atom attributes for style <I>cfg</I> must
begin with "id type xs ys zs", since these quantities are needed to
write the CFG files in the appropriate format (though the "id" and
"type" fields do not appear explicitly in the file). Any remaining
attributes will be stored as "auxiliary properties" in the CFG files.
Note that you will typically want to use the <A HREF = "dump_modify.html">dump_modify
element</A> command with CFG-formatted files, to
associate element names with atom types, so that AtomEye can render
atoms appropriately.
</P>
<P>The <I>dcd</I> style writes DCD files, a standard atomic trajectory format
used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD
files are binary and thus may not be portable to different machines.
The number of atoms per snapshot cannot change with the <I>dcd</I> style.
The <I>unwrap</I> option of the <A HREF = "dump_modify.html">dump_modify</A> command
allows DCD coordinates to be written "unwrapped" by the image flags
for each atom. Unwrapped means that if the atom has passed through
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that these coordinates may thus be far outside
the box size stored with the snapshot.
</P>
<P>The <I>xtc</I> style writes XTC files, a compressed trajectory format used
by the GROMACS molecular dynamics package, and described
<A HREF = "http://manual.gromacs.org/current/online/xtc.html">here</A>.
The precision used in XTC files can be adjusted via the
<A HREF = "dump_modify.html">dump_modify</A> command. The default value of 1000
means that coordinates are stored to 1/1000 nanometer accuracy. XTC
files are portable binary files written in the NFS XDR data format,
so that any machine which supports XDR should be able to read them.
The number of atoms per snapshot cannot change with the <I>xtc</I> style.
The <I>unwrap</I> option of the <A HREF = "dump_modify.html">dump_modify</A> command allows
XTC coordinates to be written "unwrapped" by the image flags for each
atom. Unwrapped means that if the atom has passed thru a periodic
boundary one or more times, the value is printed for what the
coordinate would be if it had not been wrapped back into the periodic
box. Note that these coordinates may thus be far outside the box size
stored with the snapshot.
</P>
<P>The <I>xyz</I> style writes XYZ files, which is a simple text-based
coordinate format that many codes can read.
</P>
<P>Note that DCD, XTC, and XYZ formatted files can be read directly by
<A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD</A> (a popular molecular viewing
program). See <A HREF = "Section_tools.html#vmd">this section</A> of the manual and
the tools/lmp2vmd/README.txt file for more information about support
in VMD for reading and visualizing LAMMPS dump files.
</P>
<HR>
<P>Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the <A HREF = "dump_modify.html">dump_modify first</A> command, which
can be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the <A HREF = "dump_modify.html">dump_modify every</A> command (not allowed
for <I>dcd</I> style).
</P>
<P>The specified filename determines how the dump file(s) is written.
The default is to write one large text file, which is opened when the
dump command is invoked and closed when an <A HREF = "undump.html">undump</A>
command is used or when LAMMPS exits. For the <I>dcd</I> and <I>xtc</I> styles,
this is a single large binary file.
</P>
<P>Dump filenames can contain two wildcard characters. If a "*"
character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc. This option is not available for the <I>dcd</I> and
-<I>xtc</I> styles.
+<I>xtc</I> styles. Note that the <A HREF = "dump_modify.html">dump_modify pad</A>
+command can be used to insure all timestep numbers are the same length
+(e.g. 00010), which can make it easier to read a series of dump files
+in order by some post-processing tools.
</P>
<P>If a "%" character appears in the filename, then one file is written
for each processor and the "%" character is replaced with the
processor ID from 0 to P-1. For example, tmp.dump.% becomes
tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller
files and can be a fast mode of output on parallel machines that
support parallel I/O for output. This option is not available for the
<I>dcd</I>, <I>xtc</I>, and <I>xyz</I> styles.
</P>
<P>Note that the "*" and "%" characters can be used together to produce a
large number of small dump files!
</P>
<P>If the filename ends with ".bin", the dump file (or files, if "*" or
"%" is also used) is written in binary format. A binary dump file
will be about the same size as a text version, but will typically
write out much faster. Of course, when post-processing, you will need
to convert it back to text format (see the <A HREF = "Section_tools.html#binary">binary2txt
tool</A>) or write your own code to read the
binary file. The format of the binary file can be understood by
looking at the tools/binary2txt.cpp file. This option is only
available for the <I>atom</I> and <I>custom</I> styles.
</P>
<P>If the filename ends with ".gz", the dump file (or files, if "*" or "%"
is also used) is written in gzipped format. A gzipped dump file will
be about 3x smaller than the text version, but will also take longer
to write. This option is not available for the <I>dcd</I> and <I>xtc</I>
styles.
</P>
<HR>
<P>This section explains the local attributes that can be specified as
part of the <I>local</I> style.
</P>
<P>The <I>index</I> attribute can be used to generate an index number from 1
to N for each line written into the dump file, where N is the total
number of local datums from all processors, or lines of output that
will appear in the snapshot. Note that because data from different
processors depend on what atoms they currently own, and atoms migrate
between processor, there is no guarantee that the same index will be
used for the same info (e.g. a particular bond) in successive
snapshots.
</P>
<P>The <I>c_ID</I> and <I>c_ID[N]</I> attributes allow local vectors or arrays
calculated by a <A HREF = "compute.html">compute</A> to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
<A HREF = "compute.html">compute</A> command for details. There are computes for
calculating local information such as indices, types, and energies for
bonds and angles.
</P>
<P>Note that computes which calculate global or per-atom quantities, as
opposed to local quantities, cannot be output in a dump local command.
Instead, global quantities can be output by the <A HREF = "thermo_style.html">thermo_style
custom</A> command, and per-atom quantities can be
output by the dump custom command.
</P>
<P>If <I>c_ID</I> is used as a attribute, then the local vector calculated by
the compute is printed. If <I>c_ID[N]</I> is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length local
array calculated by the compute.
</P>
<P>The <I>f_ID</I> and <I>f_ID[N]</I> attributes allow local vectors or arrays
calculated by a <A HREF = "fix.html">fix</A> to be output. The ID in the attribute
should be replaced by the actual ID of the fix that has been defined
previously in the input script.
</P>
<P>If <I>f_ID</I> is used as a attribute, then the local vector calculated by
the fix is printed. If <I>f_ID[N]</I> is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length local
array calculated by the fix.
</P>
<HR>
<P>This section explains the atom attributes that can be specified as
part of the <I>custom</I> and <I>cfg</I> styles.
</P>
<P>The <I>id</I>, <I>mol</I>, <I>type</I>, <I>mass</I>, <I>vx</I>, <I>vy</I>, <I>vz</I>, <I>fx</I>, <I>fy</I>,
<I>fz</I>, <I>q</I> attributes are self-explanatory.
</P>
<P><I>Id</I> is the atom ID. <I>Mol</I> is the molecule ID, included in the data
file for molecular systems. <I>Type</I> is the atom type. <I>Mass</I> is the
atom mass. <I>Vx</I>, <I>vy</I>, <I>vz</I>, <I>fx</I>, <I>fy</I>, <I>fz</I>, and <I>q</I> are components
of atom velocity and force and atomic charge.
</P>
<P>There are several options for outputting atom coordinates. The <I>x</I>,
<I>y</I>, <I>z</I> attributes write atom coordinates "unscaled", in the
appropriate distance <A HREF = "units.html">units</A> (Angstroms, sigma, etc). Use
<I>xs</I>, <I>ys</I>, <I>zs</I> if you want the coordinates "scaled" to the box size,
so that each value is 0.0 to 1.0. If the simluation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. Use
<I>xu</I>, <I>yu</I>, <I>zu</I> if you want the coordinates "unwrapped" by the image
flags for each atom. Unwrapped means that if the atom has passed thru
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that using <I>xu</I>, <I>yu</I>, <I>zu</I> means that the
coordinate values may be far outside the box bounds printed with the
snapshot. The image flags can be printed directly using the <I>ix</I>,
<I>iy</I>, <I>iz</I> attributes. The <A HREF = "dump_modify.html">dump_modify</A> command
describes in more detail what is meant by scaled vs unscaled
coordinates and the image flags.
</P>
<P>The <I>mux</I>, <I>muy</I>, <I>muz</I> attributes are specific to dipolar systems
defined with an atom style of <I>dipole</I>. They give the orientation of
the atom's point dipole moment.
</P>
<P>The <I>radius</I> attribute is specific to extended spherical particles
that have a finite size, such as granular particles defined with
an atom style of <I>granular</I>.
</P>
<P>The <I>omegax</I>, <I>omegay</I>, and <I>omegaz</I> attributes are specific to extended
spherical or aspherical particles that have an angular velocity. Only
certain atom styles, such as <I>granular</I> or <I>dipole</I> define this
quantity.
</P>
<P>The <I>angmomx</I>, <I>angmomy</I>, and <I>angmomz</I> attributes are specific to
extended aspherical particles that have an angular momentum. Only
the <I>ellipsoid</I> atom style defines this quantity.
</P>
<P>The <I>quatw</I>, <I>quati</I>, <I>quatj</I>, <I>quatk</I> attributes are for aspherical
particles defined with an atom style of <I>ellipsoid</I>. They are the
components of the quaternion that defines the orientation of the
particle.
</P>
<P>The <I>tqx</I>, <I>tqy</I>, <I>tqz</I> attributes are for extended spherical or
aspherical particles that can sustain a rotational torque due
to interactions with other particles.
</P>
<P>The <I>spin</I>, <I>eradius</I>, <I>ervel</I>, and <I>erforce</I> attributes are for
particles that represent nuclei and electrons modeled with the
electronic force field (EFF). See <A HREF = "atom_style.html">atom_style
electron</A> and <A HREF = "pair_eff.html">pair_style eff</A> for more
details.
</P>
<P>The <I>c_ID</I> and <I>c_ID[N]</I> attributes allow per-atom vectors or arrays
calculated by a <A HREF = "compute.html">compute</A> to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
<A HREF = "compute.html">compute</A> command for details. There are computes for
calculating the per-atom energy, stress, centro-symmetry parameter,
and coordination number of individual atoms.
</P>
<P>Note that computes which calculate global or local quantities, as
opposed to per-atom quantities, cannot be output in a dump custom
command. Instead, global quantities can be output by the
<A HREF = "thermo_style.html">thermo_style custom</A> command, and local quantities
can be output by the dump local command.
</P>
<P>If <I>c_ID</I> is used as a attribute, then the per-atom vector calculated
by the compute is printed. If <I>c_ID[N]</I> is used, then N must be in
the range from 1-M, which will print the Nth column of the M-length
per-atom array calculated by the compute.
</P>
<P>The <I>f_ID</I> and <I>f_ID[N]</I> attributes allow vector or array per-atom
quantities calculated by a <A HREF = "fix.html">fix</A> to be output. The ID in the
attribute should be replaced by the actual ID of the fix that has been
defined previously in the input script. The <A HREF = "fix_ave_atom.html">fix
ave/atom</A> command is one that calculates per-atom
quantities. Since it can time-average per-atom quantities produced by
any <A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or atom-style
<A HREF = "variable.html">variable</A>, this allows those time-averaged results to
be written to a dump file.
</P>
<P>If <I>f_ID</I> is used as a attribute, then the per-atom vector calculated
by the fix is printed. If <I>f_ID[N]</I> is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length
per-atom array calculated by the fix.
</P>
<P>The <I>v_name</I> attribute allows per-atom vectors calculated by a
<A HREF = "variable.html">variable</A> to be output. The name in the attribute
should be replaced by the actual name of the variable that has been
defined previously in the input script. Only an atom-style variable
can be referenced, since it is the only style that generates per-atom
values. Variables of style <I>atom</I> can reference individual atom
attributes, per-atom atom attributes, thermodynamic keywords, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of creating quantities to output to a
dump file.
</P>
<P>See <A HREF = "Section_modify.html">this section</A> of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>To write gzipped dump files, you must compile LAMMPS with the
-DLAMMPS_GZIP option - see the <A HREF = "Section_start.html#2_2">Making LAMMPS</A>
section of the documentation.
</P>
<P>The <I>xtc</I> style is part of the "xtc" package. It is only enabled if
LAMMPS was built with that package. See the <A HREF = "Section_start.html#2_3">Making
LAMMPS</A> section for more info. This is because
some machines may not support the low-level XDR data format that XTC
files are written with, which will result in a compile-time error when
a low-level include file is not found. Putting this style in a package
makes it easy to exclude from a LAMMPS build for those machines.
However, the XTC package also includes two compatibility header files
and associated functions, which should be a suitable substitute on
machines that do not have the appropriate native header files. This
option can be invoked at build time by adding -DLAMMPS_XDR to the
CCFLAGS variable in the appropriate low-level Makefile,
e.g. src/MAKE/Makefile.foo. This compatibility mode has been tested
successfully on Cray XT3/XT4/XT5 and IBM BlueGene/L machines and
should also work on IBM BG/P, and Windows XP/Vista/7 machines.
</P>
<P><B>Related commands:</B>
</P>
-<P><A HREF = "dump_modify.html">dump_modify</A>, <A HREF = "undump.html">undump</A>
+<P><A HREF = "dump_image.html">dump image</A>, <A HREF = "dump_modify.html">dump_modify</A>,
+<A HREF = "undump.html">undump</A>
+</P>
+<P><B>Default:</B>
</P>
-<P><B>Default:</B> none
+<P>The defaults for the image style are listed on the <A HREF = "dump_image.html">dump
+image</A> doc page.
</P>
</HTML>
diff --git a/doc/dump.txt b/doc/dump.txt
index 1c86bc6d9..fc58195da 100644
--- a/doc/dump.txt
+++ b/doc/dump.txt
@@ -1,485 +1,506 @@
"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
dump command :h3
+"dump image"_dump_image.html command :h3
[Syntax:]
dump ID group-ID style N file args :pre
ID = user-assigned name for the dump :ulb,l
group-ID = ID of the group of atoms to be dumped :l
-style = {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {local} or {custom} :l
+style = {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {image} or {local} or {custom} :l
N = dump every this many timesteps :l
file = name of file to write dump info to :l
args = list of arguments for a particular style :l
{atom} args = none
{cfg} args = same as {custom} args, see below
{dcd} args = none
{xtc} args = none
{xyz} args = none :pre
+ {image} args = discussed on "dump image"_dump_image.html doc page :pre
+
{local} args = list of local attributes
possible attributes = index, c_ID, c_ID\[N\], f_ID, f_ID\[N\]
index = enumeration of local values
c_ID = local vector calculated by a compute with ID
c_ID\[N\] = Nth column of local array calculated by a compute with ID
f_ID = local vector calculated by a fix with ID
f_ID\[N\] = Nth column of local array calculated by a fix with ID :pre
-
+
{custom} args = list of atom attributes
possible attributes = id, mol, type, mass,
x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz,
radius, omegax, omegay, omegaz,
angmomx, angmomy, angmomz,
quatw, quati, quatj, quatk, tqx, tqy, tqz,
spin, eradius, ervel, erforce,
c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :pre
id = atom ID
mol = molecule ID
type = atom type
mass = atom mass
x,y,z = unscaled atom coordinates
xs,ys,zs = scaled atom coordinates
xu,yu,zu = unwrapped atom coordinates
ix,iy,iz = box image that the atom is in
vx,vy,vz = atom velocities
fx,fy,fz = forces on atoms
q = atom charge
mux,muy,muz = orientation of dipolar atom
radius = radius of extended spherical particle
omegax,omegay,omegaz = angular velocity of extended particle
angmomx,angmomy,angmomz = angular momentum of extended particle
quatw,quati,quatj,quatk = quaternion components for aspherical particles
tqx,tqy,tqz = torque on extended particles
spin = electron spin
eradius = electron radius
ervel = electron radial velocity
erforce = electron radial force
c_ID = per-atom vector calculated by a compute with ID
c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name :pre
:ule
[Examples:]
dump myDump all atom 100 dump.atom
dump 2 subgroup atom 50 dump.run.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4b flow custom 100 dump.%.myforce id type c_myF\[3\] v_ke
dump 2 inner cfg 10 dump.snap.*.cfg id type xs ys zs vx vy vz
dump snap all cfg 100 dump.config.*.cfg id type xs ys zs id type c_Stress[2]
dump 1 all xtc 1000 file.xtc
dump e_data all custom 100 dump.eff id type x y z spin eradius fx fy fz eforce :pre
[Description:]
Dump a snapshot of atom quantities to one or more files every N
-timesteps in one of several styles. As described below, the filename
-determines the kind of output (text or binary or gzipped, one big file
-or one per timestep, one big file or one per processor). Only
-information for atoms in the specified group is dumped. The
-"dump_modify"_dump_modify.html command can also alter what atoms are
-included. Not all styles support all these options; see details
-below.
+timesteps in one of several styles. The {image} style is the
+exception; it creates a JPG or PPM image file of the atom
+configuration every N timesteps, as discussed on the "dump
+image"_dump_image.html doc page.
+
+Only information for atoms in the specified group is dumped. The
+"dump_modify thresh and region"_dump_modify.html commands can also
+alter what atoms are included. Not all styles support all these
+options; see details below.
+
+As described below, the filename determines the kind of output (text
+or binary or gzipped, one big file or one per timestep, one big file
+or one per processor).
IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom written to a dump file may be slightly outside the simulation
box.
IMPORTANT NOTE: Unless the "dump_modify sort"_dump_modify.html option
is invoked, the lines of atom information written to dump files
(typically one line per atom) will be in an indeterminate order for
each snapshot. This is even true when running on a single processor,
if the "atom_modify sort"_atom_modify.html option is on, which it is
by default. In this case atoms are re-ordered periodically during a
simulation, due to spatial sorting. It is also true when running in
parallel, because data for a single snapshot is collected from
multiple processors.
For the {atom}, {custom}, {cfg}, and {local} styles, sorting is off by
default. For the {dcd}, {xtc}, and {xyz} styles, sorting by atom ID
is on by default. See the "dump_modify"_dump_modify.html doc page for
details.
:line
The {style} keyword determines what atom quantities are written to the
file and in what format. Settings made via the
"dump_modify"_dump_modify.html command can also alter the format of
individual values and the file itself.
The {atom}, {local}, and {custom} styles create files in a simple text
format that is self-explanatory when viewing a dump file. Many of the
LAMMPS "post-processing tools"_Section_tools.html, including
"Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html, work with
this format.
For post-processing purposes the {atom} and {custom} text files are
self-describing in the following sense.
The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:
-ITEM: BOX BOUNDS
+ITEM: BOX BOUNDS xx yy zz
xlo xhi
ylo yhi
zlo zhi :pre
where xlo,xhi are the maximum extents of the simulation box in the
-x-dimension, and similarly for y and z.
+x-dimension, and similarly for y and z. The "xx yy zz" represent 6
+characters that encode the style of boundary for each of the 6
+simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each
+flag is either p = periodic, f = fixed, s = shrink wrap, or m = shrink
+wrapped with a minimum value. See the "boundary"_doc/boundary.html
+command for details.
For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
formatted as follows:
-ITEM: BOX BOUNDS xy xz yz
+ITEM: BOX BOUNDS xx yy zz xy xz yz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz :pre
This bounding box is convenient for many visualization programs.
See "this section"_Section_howto.html#4_12 of the doc pages for a
geometric description of triclinic boxes, as defined by LAMMPS, simple
formulas for how the 6 bounding box extents (xlo_bound,xhi_bound,etc)
are calculated from the triclinic parameters, and how to transform
those parameters to and from other commonly used triclinic
representations.
The "ITEM: ATOMS" line in each snapshot lists column descriptors for
the per-atom lines that follow. For example, the descriptors would be
"id type xs ys zs" for the default {atom} style, and would be the atom
attributes you specify in the dump command for the {custom} style.
For style {atom}, atom coordinates are written to the file, along with
the atom ID and atom type. By default, atom coords are written in a
scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom
is at a location 1/4 of the distance from xlo to xhi of the box
boundaries. The format can be changed to unscaled coords via the
"dump_modify"_dump_modify.html settings. Image flags can also be
added for each atom via dump_modify.
Style {custom} allows you to specify a list of atom attributes to be
written to the dump file for each atom. Possible attributes are
listed above and will appear in the order specified. You cannot
specify a quantity that is not defined for a particular simulation -
such as {q} for atom style {bond}, since that atom style doesn't
assign charges. Dumps occur at the very end of a timestep, so atom
attributes will include effects due to fixes that are applied during
the timestep. An explanation of the possible dump custom attributes
is given below.
For style {local}, local output generated by "computes"_compute.html
and "fixes"_fix.html is used to gnerate lines of output that is
written to the dump file. This local data is typically calculated by
each processor based on the atoms it owns, but there may be zero or
more entities per atom, e.g. a list of bond distances. An explanation
of the possible dump local attributes is given below. Note that by
using input from the "compute
property/local"_compute_property_local.html command with dump local,
it is possible to generate information on bonds, angles, etc that can
be cut and pasted directly into a data file read by the
"read_data"_read_data.html command.
Style {cfg} has the same command syntax as style {custom} and writes
extended CFG format files, as used by the
"AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A visualization
package. Since the extended CFG format uses a single snapshot of the
system per file, a wildcard "*" must be included in the filename, as
discussed below. The list of atom attributes for style {cfg} must
begin with "id type xs ys zs", since these quantities are needed to
write the CFG files in the appropriate format (though the "id" and
"type" fields do not appear explicitly in the file). Any remaining
attributes will be stored as "auxiliary properties" in the CFG files.
Note that you will typically want to use the "dump_modify
element"_dump_modify.html command with CFG-formatted files, to
associate element names with atom types, so that AtomEye can render
atoms appropriately.
The {dcd} style writes DCD files, a standard atomic trajectory format
used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD
files are binary and thus may not be portable to different machines.
The number of atoms per snapshot cannot change with the {dcd} style.
The {unwrap} option of the "dump_modify"_dump_modify.html command
allows DCD coordinates to be written "unwrapped" by the image flags
for each atom. Unwrapped means that if the atom has passed through
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that these coordinates may thus be far outside
the box size stored with the snapshot.
The {xtc} style writes XTC files, a compressed trajectory format used
by the GROMACS molecular dynamics package, and described
"here"_http://manual.gromacs.org/current/online/xtc.html.
The precision used in XTC files can be adjusted via the
"dump_modify"_dump_modify.html command. The default value of 1000
means that coordinates are stored to 1/1000 nanometer accuracy. XTC
files are portable binary files written in the NFS XDR data format,
so that any machine which supports XDR should be able to read them.
The number of atoms per snapshot cannot change with the {xtc} style.
The {unwrap} option of the "dump_modify"_dump_modify.html command allows
XTC coordinates to be written "unwrapped" by the image flags for each
atom. Unwrapped means that if the atom has passed thru a periodic
boundary one or more times, the value is printed for what the
coordinate would be if it had not been wrapped back into the periodic
box. Note that these coordinates may thus be far outside the box size
stored with the snapshot.
The {xyz} style writes XYZ files, which is a simple text-based
coordinate format that many codes can read.
Note that DCD, XTC, and XYZ formatted files can be read directly by
"VMD"_http://www.ks.uiuc.edu/Research/vmd (a popular molecular viewing
program). See "this section"_Section_tools.html#vmd of the manual and
the tools/lmp2vmd/README.txt file for more information about support
in VMD for reading and visualizing LAMMPS dump files.
:line
Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the "dump_modify first"_dump_modify.html command, which
can be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the "dump_modify every"_dump_modify.html command (not allowed
for {dcd} style).
The specified filename determines how the dump file(s) is written.
The default is to write one large text file, which is opened when the
dump command is invoked and closed when an "undump"_undump.html
command is used or when LAMMPS exits. For the {dcd} and {xtc} styles,
this is a single large binary file.
Dump filenames can contain two wildcard characters. If a "*"
character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc. This option is not available for the {dcd} and
-{xtc} styles.
+{xtc} styles. Note that the "dump_modify pad"_dump_modify.html
+command can be used to insure all timestep numbers are the same length
+(e.g. 00010), which can make it easier to read a series of dump files
+in order by some post-processing tools.
If a "%" character appears in the filename, then one file is written
for each processor and the "%" character is replaced with the
processor ID from 0 to P-1. For example, tmp.dump.% becomes
tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller
files and can be a fast mode of output on parallel machines that
support parallel I/O for output. This option is not available for the
{dcd}, {xtc}, and {xyz} styles.
Note that the "*" and "%" characters can be used together to produce a
large number of small dump files!
If the filename ends with ".bin", the dump file (or files, if "*" or
"%" is also used) is written in binary format. A binary dump file
will be about the same size as a text version, but will typically
write out much faster. Of course, when post-processing, you will need
to convert it back to text format (see the "binary2txt
tool"_Section_tools.html#binary) or write your own code to read the
binary file. The format of the binary file can be understood by
looking at the tools/binary2txt.cpp file. This option is only
available for the {atom} and {custom} styles.
If the filename ends with ".gz", the dump file (or files, if "*" or "%"
is also used) is written in gzipped format. A gzipped dump file will
be about 3x smaller than the text version, but will also take longer
to write. This option is not available for the {dcd} and {xtc}
styles.
:line
This section explains the local attributes that can be specified as
part of the {local} style.
The {index} attribute can be used to generate an index number from 1
to N for each line written into the dump file, where N is the total
number of local datums from all processors, or lines of output that
will appear in the snapshot. Note that because data from different
processors depend on what atoms they currently own, and atoms migrate
between processor, there is no guarantee that the same index will be
used for the same info (e.g. a particular bond) in successive
snapshots.
The {c_ID} and {c_ID\[N\]} attributes allow local vectors or arrays
calculated by a "compute"_compute.html to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
"compute"_compute.html command for details. There are computes for
calculating local information such as indices, types, and energies for
bonds and angles.
Note that computes which calculate global or per-atom quantities, as
opposed to local quantities, cannot be output in a dump local command.
Instead, global quantities can be output by the "thermo_style
custom"_thermo_style.html command, and per-atom quantities can be
output by the dump custom command.
If {c_ID} is used as a attribute, then the local vector calculated by
the compute is printed. If {c_ID\[N\]} is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length local
array calculated by the compute.
The {f_ID} and {f_ID\[N\]} attributes allow local vectors or arrays
calculated by a "fix"_fix.html to be output. The ID in the attribute
should be replaced by the actual ID of the fix that has been defined
previously in the input script.
If {f_ID} is used as a attribute, then the local vector calculated by
the fix is printed. If {f_ID\[N\]} is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length local
array calculated by the fix.
:line
This section explains the atom attributes that can be specified as
part of the {custom} and {cfg} styles.
The {id}, {mol}, {type}, {mass}, {vx}, {vy}, {vz}, {fx}, {fy},
{fz}, {q} attributes are self-explanatory.
{Id} is the atom ID. {Mol} is the molecule ID, included in the data
file for molecular systems. {Type} is the atom type. {Mass} is the
atom mass. {Vx}, {vy}, {vz}, {fx}, {fy}, {fz}, and {q} are components
of atom velocity and force and atomic charge.
There are several options for outputting atom coordinates. The {x},
{y}, {z} attributes write atom coordinates "unscaled", in the
appropriate distance "units"_units.html (Angstroms, sigma, etc). Use
{xs}, {ys}, {zs} if you want the coordinates "scaled" to the box size,
so that each value is 0.0 to 1.0. If the simluation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. Use
{xu}, {yu}, {zu} if you want the coordinates "unwrapped" by the image
flags for each atom. Unwrapped means that if the atom has passed thru
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that using {xu}, {yu}, {zu} means that the
coordinate values may be far outside the box bounds printed with the
snapshot. The image flags can be printed directly using the {ix},
{iy}, {iz} attributes. The "dump_modify"_dump_modify.html command
describes in more detail what is meant by scaled vs unscaled
coordinates and the image flags.
The {mux}, {muy}, {muz} attributes are specific to dipolar systems
defined with an atom style of {dipole}. They give the orientation of
the atom's point dipole moment.
The {radius} attribute is specific to extended spherical particles
that have a finite size, such as granular particles defined with
an atom style of {granular}.
The {omegax}, {omegay}, and {omegaz} attributes are specific to extended
spherical or aspherical particles that have an angular velocity. Only
certain atom styles, such as {granular} or {dipole} define this
quantity.
The {angmomx}, {angmomy}, and {angmomz} attributes are specific to
extended aspherical particles that have an angular momentum. Only
the {ellipsoid} atom style defines this quantity.
The {quatw}, {quati}, {quatj}, {quatk} attributes are for aspherical
particles defined with an atom style of {ellipsoid}. They are the
components of the quaternion that defines the orientation of the
particle.
The {tqx}, {tqy}, {tqz} attributes are for extended spherical or
aspherical particles that can sustain a rotational torque due
to interactions with other particles.
The {spin}, {eradius}, {ervel}, and {erforce} attributes are for
particles that represent nuclei and electrons modeled with the
electronic force field (EFF). See "atom_style
electron"_atom_style.html and "pair_style eff"_pair_eff.html for more
details.
The {c_ID} and {c_ID\[N\]} attributes allow per-atom vectors or arrays
calculated by a "compute"_compute.html to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
"compute"_compute.html command for details. There are computes for
calculating the per-atom energy, stress, centro-symmetry parameter,
and coordination number of individual atoms.
Note that computes which calculate global or local quantities, as
opposed to per-atom quantities, cannot be output in a dump custom
command. Instead, global quantities can be output by the
"thermo_style custom"_thermo_style.html command, and local quantities
can be output by the dump local command.
If {c_ID} is used as a attribute, then the per-atom vector calculated
by the compute is printed. If {c_ID\[N\]} is used, then N must be in
the range from 1-M, which will print the Nth column of the M-length
per-atom array calculated by the compute.
The {f_ID} and {f_ID\[N\]} attributes allow vector or array per-atom
quantities calculated by a "fix"_fix.html to be output. The ID in the
attribute should be replaced by the actual ID of the fix that has been
defined previously in the input script. The "fix
ave/atom"_fix_ave_atom.html command is one that calculates per-atom
quantities. Since it can time-average per-atom quantities produced by
any "compute"_compute.html, "fix"_fix.html, or atom-style
"variable"_variable.html, this allows those time-averaged results to
be written to a dump file.
If {f_ID} is used as a attribute, then the per-atom vector calculated
by the fix is printed. If {f_ID\[N\]} is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length
per-atom array calculated by the fix.
The {v_name} attribute allows per-atom vectors calculated by a
"variable"_variable.html to be output. The name in the attribute
should be replaced by the actual name of the variable that has been
defined previously in the input script. Only an atom-style variable
can be referenced, since it is the only style that generates per-atom
values. Variables of style {atom} can reference individual atom
attributes, per-atom atom attributes, thermodynamic keywords, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of creating quantities to output to a
dump file.
See "this section"_Section_modify.html of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.
:line
[Restrictions:]
To write gzipped dump files, you must compile LAMMPS with the
-DLAMMPS_GZIP option - see the "Making LAMMPS"_Section_start.html#2_2
section of the documentation.
The {xtc} style is part of the "xtc" package. It is only enabled if
LAMMPS was built with that package. See the "Making
LAMMPS"_Section_start.html#2_3 section for more info. This is because
some machines may not support the low-level XDR data format that XTC
files are written with, which will result in a compile-time error when
a low-level include file is not found. Putting this style in a package
makes it easy to exclude from a LAMMPS build for those machines.
However, the XTC package also includes two compatibility header files
and associated functions, which should be a suitable substitute on
machines that do not have the appropriate native header files. This
option can be invoked at build time by adding -DLAMMPS_XDR to the
CCFLAGS variable in the appropriate low-level Makefile,
e.g. src/MAKE/Makefile.foo. This compatibility mode has been tested
successfully on Cray XT3/XT4/XT5 and IBM BlueGene/L machines and
should also work on IBM BG/P, and Windows XP/Vista/7 machines.
[Related commands:]
-"dump_modify"_dump_modify.html, "undump"_undump.html
+"dump image"_dump_image.html, "dump_modify"_dump_modify.html,
+"undump"_undump.html
+
+[Default:]
-[Default:] none
+The defaults for the image style are listed on the "dump
+image"_dump_image.html doc page.
diff --git a/doc/dump_image.html b/doc/dump_image.html
new file mode 100644
index 000000000..82826a4fd
--- /dev/null
+++ b/doc/dump_image.html
@@ -0,0 +1,430 @@
+<HTML>
+<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
+</CENTER>
+
+
+
+
+
+
+<HR>
+
+<H3>dump image command
+</H3>
+<P><B>Syntax:</B>
+</P>
+<PRE>dump ID group-ID image N file keyword value ...
+</PRE>
+<UL><LI>ID = user-assigned name for the dump
+
+<LI>group-ID = ID of the group of atoms to be imaged
+
+<LI>image = style of dump command (other styles <I>atom</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>local</I> or <I>custom</I> are discussed on the <A HREF = "dump.html">dump</A> doc page)
+
+<LI>N = dump every this many timesteps
+
+<LI>file = name of file to write image to
+
+<LI>zero or more keyword/value pairs may be appended
+
+<LI>keyword = <I>atom</I> or <I>bond</I> or <I>size</I> or <I>view</I> or <I>center</I> or <I>up</I> or <I>zoom</I> or <I>persp</I> or <I>box</I> or <I>dynamic</I> or <I>box</I> or <I>axes</I> or <I>shiny</I> or <I>ssao</I>
+
+<PRE> <I>atom</I> values = color diam
+ color = <I>none</I> or <I>type</I> or <I>element</I> or atom-attribute
+ diam = D or <I>type</I> or <I>element</I> or <I>radius</I> or <I>shape</I> or atom-attribute
+ D = numeric value for atom diameter (distance units)
+ <I>bond</I> values = color diam
+ color = <I>none</I> or <I>atom</I> or <I>type</I>
+ diam = D or <I>type</I>
+ D = numeric value for bond diameter (distance units)
+ <I>size</I> values = width height
+ width = width of image in # of pixels
+ height = height of image in # of pixels
+ <I>view</I> values = theta phi
+ theta = view angle from +z axis (degrees)
+ phi = azimuthal view angle (degrees)
+ theta or phi can be a variable (see below)
+ <I>center</I> values = flag Cx Cy Cz = center point of image (distance units)
+ flag = "s" for static, "d" for dynamic
+ Cx,Cy,Cz can be variables (see below)
+ <I>up</I> values = Ux Uy Uz = components of up vector
+ Ux,Uy,Uz can be variables (see below)
+ <I>zoom</I> value = factor = scale image size by this factor
+ factor can be a variable (see below)
+ <I>persp</I> value = factor = perspective setting
+ factor can be a variable (see below)
+ <I>box</I> values = yes/no diam
+ yes/no = do or do not draw simulation box lines
+ diam = diameter of box lines as fraction of shortest box length
+ <I>axes</I> values = yes/no length diam
+ yes/no = do or do not draw xyz axes lines next to simulation box
+ length = length of axes lines as fraction of respective box lengths
+ diam = diameter of axes lines as fraction of shortest box length
+ <I>shiny</I> value = factor
+ factor = shinyness of spheres and cylinders from 0.0 to 1.0
+ <I>ssao</I> value = yes/no
+ yes/no = turn on/off SSAO depth shading
+</PRE>
+
+</UL>
+<P><B>Examples:</B>
+</P>
+<PRE>dump myDump all image 100 dump.*.jpg
+</PRE>
+<P><B>Description:</B>
+</P>
+<P>Dump an image (picture) of the atom configuration every N timesteps as
+either a JPG or PPM file. A series of such images can easily be
+converted into an animated movie of your simulation; see further
+details below. Other dump styles store snapshots of atom quantities
+in various formats, as discussed on the <A HREF = "dump.html">dump</A> doc page.
+</P>
+<P>Only atoms in the specified group are rendered in the image. The
+<A HREF = "dump_modify.html">dump_modify region and thresh</A> commands can also
+alter what atoms are included in the image.
+</P>
+<P>The filename suffix determines whether a JPG or PPM file is created.
+If the suffix is ".jpg" or ".jpeg", then a JPG file is created, else a
+PPM file is created. To write out JPG files, you must build LAMMPS
+with a JPEG library. See <A HREF = "Section_start.html#2_2_4">this section</A> of
+the manual for instructions on how to do this.
+</P>
+<P>IMPORTANT NOTE: Because periodic boundary conditions are enforced only
+on timesteps when neighbor lists are rebuilt, the coordinates of an
+atom image may be slightly outside the simulation box.
+</P>
+<HR>
+
+<P>Dumps are performed on timesteps that are a multiple of N (including
+timestep 0) and on the last timestep of a minimization if the
+minimization converges. Note that this means a dump will not be
+performed on the initial timestep after the dump command is invoked,
+if the current timestep is not a multiple of N. This behavior can be
+changed via the <A HREF = "dump_modify.html">dump_modify first</A> command, which
+can be useful if the dump command is invoked after a minimization
+ended on an arbitrary timestep. N can be changed between runs by
+using the <A HREF = "dump_modify.html">dump_modify every</A> command (not allowed
+for <I>dcd</I> style).
+</P>
+<P>Dump image filenames must contain a wildcard character "*". If a "*"
+character appears in the filename, then one file per snapshot is
+written and the "*" character is replaced with the timestep value.
+For example, tmp.dump.*.jpg becomes tmp.dump.0.jpg,
+tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note that the
+<A HREF = "dump_modify.html">dump_modify pad</A> command can be used to insure all
+timestep numbers are the same length (e.g. 00010), which can make it
+easier to convert a series of images into a movie in the correct
+ordering.
+</P>
+<HR>
+
+<P>The kewords listed above control how the image is rendered. As listed
+below, all of the keywords have defaults, most of which you will
+likely not need to change. The <A HREF = "dump_modify.html">dump modify</A> also
+has options specific to the dump image style, particularly for
+assigning colors to atoms, bonds, and other image features.
+</P>
+<HR>
+
+<P>The <I>atom</I> keyword determines the color and size of atoms rendered in
+the image. If <I>none</I> is specified for the color value (with any diam
+value), then no atoms are drawn.
+</P>
+<P>The color value can be <I>type</I> or <I>element</I> or an atom-attribute.
+</P>
+<P>If <I>type</I> is specified for the color
+value, then the color of each atom is determined by its atom type.
+By default the mapping of types to colors is as follows:
+</P>
+<UL><LI>type 1 = red
+<LI>type 2 = green
+<LI>type 3 = blue
+<LI>type 4 = yellow
+<LI>type 5 = aqua
+<LI>type 6 = cyan
+</UL>
+<P>and repeats itself for types > 6. This mapping can be changed by the
+<A HREF = "dump_modify.html">dump_modify acolor</A> command.
+</P>
+<P>If <I>element</I> is specified for the color value, then the color of each
+atom is determined by which element it is, which in turn is specified
+by the element-to-type mapping specified by the "dump_modify element"
+command. By default every atom type is C (carbon). Every element has
+a color associated with it, which is the same as used by the
+<A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> visualization package.
+</P>
+
+
+<P>An atom-attribute can also be used for the color value. Any attribute
+listed on the <A HREF = "dump.html">dump custom</A> doc page can be used, e.g. vx,
+fy, q, spin, etc. This includes per-atom quantities calculated by a
+<A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or <A HREF = "variable.html">variable</A>.
+For example, if "vx" is used as the per-atom attribute, then the color
+of the atom will depend on the x-component of its velocity.
+</P>
+<P>The association of a per-atom value with a specific color is
+determined by a "color map", which can be specified via the
+<A HREF = "dump_modify.html">dump_modify</A> command. The basic idea is that the
+atom-attribute will be within a range of values, and every value
+within the range is mapped to a specific color. Depending on how the
+color map is defined, that mapping can take place via interpolation so
+that a value of -3.2 is halfway between "red" and "blue", or
+discretely so that the value of -3.2 is "orange".
+</P>
+<P>The diam value can be a numeric value <I>D</I> or <I>type</I> or <I>element</I> or
+<I>radius</I> or <I>shape</I> or an atom-attribute.
+</P>
+<P>If a numeric value <I>D</I> is specified, then all atoms will be drawn with
+that diameter, e.g. 1.5, which is in distance units in whatever
+<A HREF = "units.html">units</A> you are using, e.g. Angstroms.
+</P>
+<P>If <I>type</I> is specified for the diam value then the color of each atom
+is determined by its atom type. By default all types have diameter
+1.0. This mapping can be changed by the <A HREF = "dump_modify.html">dump_modify
+adiam</A> command.
+</P>
+<P>If <I>element</I> is specified for the diam value, then the diamater of
+each atom is determined by which element it is, which in turn is
+specified by the element-to-type mapping specified by the "dump_modify
+element" command. By default every atom type is C (carbon). Every
+element has a diamtere associated with it, which is the same as used
+by the <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> visualization package.
+</P>
+<P>If <I>radius</I> or <I>shape</I> is specified for the diam value then those the
+atom style you are using must define those attributes. The radius or
+shape of the individual atom is then used to draw it. Currently, only
+spherical shapes are allowed. Support for ellipsoids will be added
+later.
+</P>
+<P>An atom-attribute can also be used for the diam value. Any attribute
+listed on the <A HREF = "dump.html">dump custom</A> doc page can be used, e.g. vx,
+fy, q, spin, etc. This includes per-atom quantities calculated by a
+<A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or <A HREF = "variable.html">variable</A>.
+For example, if "vx" is used as the per-atom attribute, then the
+diameter of the atom will depend on the x-component of its velocity,
+which will assumed to be >= 0.0, else the atom will not be drawn.
+</P>
+<HR>
+
+<P>The <I>bond</I> keyword determines the color and thickness or diameter of
+bonds rendered in the image. If <I>none</I> is specified for the color
+value (with any diam value), then no bonds are drawn.
+</P>
+<P>If <I>atom</I> is specified for the color value, then the each bond is
+drawn in 2 halves, with the color of each half being the color of the
+atom at that end of the bond.
+</P>
+<P>If <I>type</I> is specified for the color value, then the color of each
+bond is determined by its bond type. By default the mapping of types
+to colors is as follows:
+</P>
+<UL><LI>type 1 = red
+<LI>type 2 = green
+<LI>type 3 = blue
+<LI>type 4 = yellow
+<LI>type 5 = aqua
+<LI>type 6 = cyan
+</UL>
+<P>and repeats itself for types > 6. This mapping can be changed by the
+<A HREF = "dump_modify.html">dump_modify bcolor</A> command.
+</P>
+<P>The diam value can be a numeric value <I>D</I> or <I>type</I>.
+</P>
+<P>If a numeric value <I>D</I> is specified, then all bond will be drawn with
+that diameter, e.g. 1.0, which is in distance units in whatever
+<A HREF = "units.html">units</A> you are using, e.g. Angstroms.
+</P>
+<P>If <I>type</I> is specified for the diam value then the color of each bond
+is determined by its bond type. By default all types have diameter
+0.5. This mapping can be changed by the <A HREF = "dump_modify.html">dump_modify
+bdiam</A> command.
+</P>
+<HR>
+
+<P>The <I>size</I> keyword determines the width and height of the created
+image files, in numbers of pixels in each direction.
+</P>
+<HR>
+
+<P>The <I>view</I>, <I>center</I>, <I>up</I>, <I>zoom</I>, and <I>persp</I> settings determine how
+3d simulation space is mapped to the 2d plane of the image. Basically
+they control how the simulation box appears in the image.
+</P>
+<P>All of the <I>view</I>, <I>center</I>, <I>up</I>, <I>zoom</I>, and <I>persp</I> settings can be
+specified as numeric values, whose meaning is explained below. But
+any of them can also be specified as an equal-style variable, by using
+v_name as the setting, where "name" is the variable name. In this
+case the variable will be evaluated on the timestep each image is
+created to create a new setting. If the equal-style variable is
+time-dependent, this is a means of changing the way the simulation box
+appears from image to image, effectively doing a pan or fly-by view of
+your simulation.
+</P>
+<P>The <I>view</I> keyword determines the viewpoint from which the simulation
+box is viewed. The <I>theta</I> setting is the vertical angle from the +z
+axis, and must be an angle from 0 to 180 degrees. The <I>phi</I> setting
+is an azimuthal angle around the z axis and can be positive or
+negative.
+</P>
+<P>The <I>center</I> keyword determines the point in simulation space that
+will be at the center of the image. <I>Cx</I>, <I>Cy</I>, and <I>Cz</I> are
+speficied as fractions of the box dimensions, so that (0.5,0.5,0.5) is
+the center of the simulation box. These values do not have to be
+between 0.0 and 1.0, if you want the simulation box to be offset from
+the center of the image. Note, however, that if you choose odd values
+for <I>Cx</I>, <I>Cy</I>, or <I>Cz</I> you may get a blank image. Internally, <I>Cx</I>,
+<I>Cy</I>, and <I>Cz</I> are converted into a point in simulation space. If
+<I>flag</I> is set to "s" for static, then this conversion is done once, at
+the time the dump command is issued. If <I>flag</I> is set to "d" for
+dynamic then the conversion is performed every time a new image is
+created. If the box size or shape is changing, this will adjust the
+center point in simulation space.
+</P>
+<P>The <I>up</I> keyword determines what direction in simulation space will be
+"up" in the image. Internally it is stored as a vector that is in the
+plane perpendicular to the view vector implied by the <I>theta</I> and
+<I>pni</I> settings, and which is in the plane defined by the view vector
+and user-specified up vector. Thus this internal vector is computed
+from the user-specified <I>up</I> vector as
+</P>
+<PRE>up_internal = view cross (up cross view)
+</PRE>
+<P>This means the only restriction on the specified <I>up</I> vector is that
+it cannot be parallel to the <I>view</I> vector, implied by the <I>theta</I> and
+<I>phi</I> settings.
+</P>
+<P>The <I>zoom</I> keyword scales the size of the simulation box as it appears
+in the image. The default <I>factor</I> setting of 1 should display an
+image mostly filled by the atoms in the simulation box. A <I>factor</I> >
+1 will make the simulation box larger; a <I>factor</I> < 1 will make it
+smaller.
+</P>
+<P>The <I>persp</I> keyword how much depth perspective is present in the
+image. Depth persepctive makes lines that are parallel in simulation
+space appear non-parallel in the image. A <I>factor</I> setting of 0.0
+means that parallel lines will meet at infininty (1.0/factor), which
+is an orthographic rendering with no persepctive. A <I>factor</I> setting
+between 0.0 and 1.0 will introduce more perspective. A <I>factor</I> > 1
+will create a highly skewed image with a large amount of perspective.
+</P>
+<P>The <I>dynamic</I> keyword
+determines the color and thickness of bonds
+rendered in the image.
+</P>
+<HR>
+
+<P>The <I>box</I> keyword determines how the simulation box boundaries are
+rendered as thin cylinders in the image. If <I>no</I> is set, then the box
+boundaries are not drawn and the <I>diam</I> setting is ignored. If <I>yes</I>
+is set, the 12 edges of the box are drawn, with a diameter that is a
+fraction of the shortest box lenght in x, y, or z. The color of the
+box boundaires can be set with the <A HREF = "dump_modify.html">dump_modify
+boxcolor</A> command.
+</P>
+<P>The <I>axes</I> keyword determines how the coordinate axes are rendered as
+thin cylinders in the image. If <I>no</I> is set, then the axes are not
+drawn and the <I>length</I> and <I>diam</I> settings are ignored. If <I>yes</I> is
+set, 3 thin cylinders are drawn to represent the x,y,z axes in colors
+red,green/blue. The origin of these cylinders will be offset
+from the lower left corner of the box by 10%. The <I>length</I> setting
+determines how long the cylinders will be. The <I>diam</I> setting
+determines their thickness.
+</P>
+<HR>
+
+<P>The <I>shiny</I> keyword determines how shiny the objects rendered in the
+image will appear. This must be a value 0.0 <= S <= 1.0, where S = 1
+is a highly-reflective surface and S = 0 is a rough non-shiny surface.
+</P>
+<P>The <I>ssao</I> keyword turns on/off a screen space ambient occlusion
+(SSAO) model for depth shading. If <I>yes</I> is set, then atoms further
+away from the viewer are darkened, which is perceived as depth by the
+viewer. The calculation of this effect can increase the cost of
+computing the image by roughly 2x. If <I>no</I> is set, the depth shading
+is not performed.
+</P>
+<HR>
+
+<P>A series of JPG or PPM images can be converted into a movie file and
+then played as a movie using commonly available tools.
+</P>
+<P>Convert JPG or PPM files into an animated GIF or MPEG or other movie
+file:
+</P>
+<UL><LI>a) Use the ImageMagick convert program.
+
+<PRE>% convert *.jpg foo.gif
+% convert *.jpg foo.mpg
+</PRE>
+<LI>b) Use QuickTime.
+
+<P>Select "Open Image Sequence" under the File menu
+Load the images into QuickTime
+Select "Export" under the File menu
+Save the movie as a QuickTime movie (*.mov) or in another format
+</P>
+<LI>c) Windows-based tool.
+</UL>
+<P>If someone tells us how to do this a common Windows-based tool, we'll
+post the instructions here.
+</P>
+<P>Play the movie:
+</P>
+<UL><LI>a) Use your browser to view an animated GIF movie.
+
+<P>Select "Open File" under the File menu
+Load the animated GIF file
+</P>
+<LI>b) Use the freely available mplayer tool to view an MPEG movie.
+
+<PRE>% mplayer foo.mpg
+</PRE>
+<LI>c) Use the <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A>
+<A HREF = "http://www.sandia.gov/~sjplimp/pizza/doc/animate.html">animate tool</A>,
+which works directly on a series of image files.
+
+<PRE>a = animate("foo*.jpg")
+</PRE>
+<LI>d) QuickTime and other Windows-based media players can
+obviously play movie files directly.
+</UL>
+<HR>
+
+<P>See <A HREF = "Section_modify.html">this section</A> of the manual for information
+on how to add new compute and fix styles to LAMMPS to calculate
+per-atom quantities which could then be output into dump files.
+</P>
+<HR>
+
+<P><B>Restrictions:</B>
+</P>
+<P>To write JPG images, you must link LAMMPS with a JPEG library - see
+the <A HREF = "Section_start.html#2_2_4">Making LAMMPS</A> section of the
+documentation for details.
+</P>
+<P><B>Related commands:</B>
+</P>
+<P><A HREF = "dump.html">dump</A>, <A HREF = "dump_modify.html">dump_modify</A>, <A HREF = "undump.html">undump</A>
+</P>
+<P><B>Default:</B>
+</P>
+<P>The defaults for the keywords are as follows:
+</P>
+<UL><LI>atom = type 1.0
+<LI>bond = none 0.0 (if no bonds in system)
+<LI>bond = atom 0.5 (if bonds in system)
+<LI>size = 512 512
+<LI>view = 60 30 (for 3d)
+<LI>view = 0 0 (for 2d)
+<LI>center = s 0.5 0.5 0.5
+<LI>up = 0 0 1 (for 3d)
+<LI>up = 0 1 0 (for 2d)
+<LI>zoom = 1.0
+<LI>persp = 0.0
+<LI>dynamic = no
+<LI>box = yes 0.01
+<LI>axes = no 0.0 0.0
+<LI>shiny = 1.0
+<LI>ssao = no
+</UL>
+</HTML>
diff --git a/doc/dump_image.txt b/doc/dump_image.txt
new file mode 100644
index 000000000..324ba2d7a
--- /dev/null
+++ b/doc/dump_image.txt
@@ -0,0 +1,417 @@
+"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
+
+dump image command :h3
+
+[Syntax:]
+
+dump ID group-ID image N file keyword value ... :pre
+
+ID = user-assigned name for the dump :ulb,l
+group-ID = ID of the group of atoms to be imaged :l
+image = style of dump command (other styles {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {local} or {custom} are discussed on the "dump"_dump.html doc page) :l
+N = dump every this many timesteps :l
+file = name of file to write image to :l
+zero or more keyword/value pairs may be appended :l
+keyword = {atom} or {bond} or {size} or {view} or {center} or {up} or {zoom} or {persp} or {box} or {dynamic} or {box} or {axes} or {shiny} or {ssao} :l
+ {atom} values = color diam
+ color = {none} or {type} or {element} or atom-attribute
+ diam = D or {type} or {element} or {radius} or {shape} or atom-attribute
+ D = numeric value for atom diameter (distance units)
+ {bond} values = color diam
+ color = {none} or {atom} or {type}
+ diam = D or {type}
+ D = numeric value for bond diameter (distance units)
+ {size} values = width height
+ width = width of image in # of pixels
+ height = height of image in # of pixels
+ {view} values = theta phi
+ theta = view angle from +z axis (degrees)
+ phi = azimuthal view angle (degrees)
+ theta or phi can be a variable (see below)
+ {center} values = flag Cx Cy Cz = center point of image (distance units)
+ flag = "s" for static, "d" for dynamic
+ Cx,Cy,Cz can be variables (see below)
+ {up} values = Ux Uy Uz = components of up vector
+ Ux,Uy,Uz can be variables (see below)
+ {zoom} value = factor = scale image size by this factor
+ factor can be a variable (see below)
+ {persp} value = factor = perspective setting
+ factor can be a variable (see below)
+ {box} values = yes/no diam
+ yes/no = do or do not draw simulation box lines
+ diam = diameter of box lines as fraction of shortest box length
+ {axes} values = yes/no length diam
+ yes/no = do or do not draw xyz axes lines next to simulation box
+ length = length of axes lines as fraction of respective box lengths
+ diam = diameter of axes lines as fraction of shortest box length
+ {shiny} value = factor
+ factor = shinyness of spheres and cylinders from 0.0 to 1.0
+ {ssao} value = yes/no
+ yes/no = turn on/off SSAO depth shading :pre
+:ule
+
+[Examples:]
+
+dump myDump all image 100 dump.*.jpg :pre
+
+[Description:]
+
+Dump an image (picture) of the atom configuration every N timesteps as
+either a JPG or PPM file. A series of such images can easily be
+converted into an animated movie of your simulation; see further
+details below. Other dump styles store snapshots of atom quantities
+in various formats, as discussed on the "dump"_dump.html doc page.
+
+Only atoms in the specified group are rendered in the image. The
+"dump_modify region and thresh"_dump_modify.html commands can also
+alter what atoms are included in the image.
+
+The filename suffix determines whether a JPG or PPM file is created.
+If the suffix is ".jpg" or ".jpeg", then a JPG file is created, else a
+PPM file is created. To write out JPG files, you must build LAMMPS
+with a JPEG library. See "this section"_Section_start.html#2_2_4 of
+the manual for instructions on how to do this.
+
+IMPORTANT NOTE: Because periodic boundary conditions are enforced only
+on timesteps when neighbor lists are rebuilt, the coordinates of an
+atom image may be slightly outside the simulation box.
+
+:line
+
+Dumps are performed on timesteps that are a multiple of N (including
+timestep 0) and on the last timestep of a minimization if the
+minimization converges. Note that this means a dump will not be
+performed on the initial timestep after the dump command is invoked,
+if the current timestep is not a multiple of N. This behavior can be
+changed via the "dump_modify first"_dump_modify.html command, which
+can be useful if the dump command is invoked after a minimization
+ended on an arbitrary timestep. N can be changed between runs by
+using the "dump_modify every"_dump_modify.html command (not allowed
+for {dcd} style).
+
+Dump image filenames must contain a wildcard character "*". If a "*"
+character appears in the filename, then one file per snapshot is
+written and the "*" character is replaced with the timestep value.
+For example, tmp.dump.*.jpg becomes tmp.dump.0.jpg,
+tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note that the
+"dump_modify pad"_dump_modify.html command can be used to insure all
+timestep numbers are the same length (e.g. 00010), which can make it
+easier to convert a series of images into a movie in the correct
+ordering.
+
+:line
+
+The kewords listed above control how the image is rendered. As listed
+below, all of the keywords have defaults, most of which you will
+likely not need to change. The "dump modify"_dump_modify.html also
+has options specific to the dump image style, particularly for
+assigning colors to atoms, bonds, and other image features.
+
+:line
+
+The {atom} keyword determines the color and size of atoms rendered in
+the image. If {none} is specified for the color value (with any diam
+value), then no atoms are drawn.
+
+The color value can be {type} or {element} or an atom-attribute.
+
+If {type} is specified for the color
+value, then the color of each atom is determined by its atom type.
+By default the mapping of types to colors is as follows:
+
+type 1 = red
+type 2 = green
+type 3 = blue
+type 4 = yellow
+type 5 = aqua
+type 6 = cyan :ul
+
+and repeats itself for types > 6. This mapping can be changed by the
+"dump_modify acolor"_dump_modify.html command.
+
+If {element} is specified for the color value, then the color of each
+atom is determined by which element it is, which in turn is specified
+by the element-to-type mapping specified by the "dump_modify element"
+command. By default every atom type is C (carbon). Every element has
+a color associated with it, which is the same as used by the
+"AtomEye"_atomeye visualization package.
+
+:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A)
+
+An atom-attribute can also be used for the color value. Any attribute
+listed on the "dump custom"_dump.html doc page can be used, e.g. vx,
+fy, q, spin, etc. This includes per-atom quantities calculated by a
+"compute"_compute.html, "fix"_fix.html, or "variable"_variable.html.
+For example, if "vx" is used as the per-atom attribute, then the color
+of the atom will depend on the x-component of its velocity.
+
+The association of a per-atom value with a specific color is
+determined by a "color map", which can be specified via the
+"dump_modify"_dump_modify.html command. The basic idea is that the
+atom-attribute will be within a range of values, and every value
+within the range is mapped to a specific color. Depending on how the
+color map is defined, that mapping can take place via interpolation so
+that a value of -3.2 is halfway between "red" and "blue", or
+discretely so that the value of -3.2 is "orange".
+
+The diam value can be a numeric value {D} or {type} or {element} or
+{radius} or {shape} or an atom-attribute.
+
+If a numeric value {D} is specified, then all atoms will be drawn with
+that diameter, e.g. 1.5, which is in distance units in whatever
+"units"_units.html you are using, e.g. Angstroms.
+
+If {type} is specified for the diam value then the color of each atom
+is determined by its atom type. By default all types have diameter
+1.0. This mapping can be changed by the "dump_modify
+adiam"_dump_modify.html command.
+
+If {element} is specified for the diam value, then the diamater of
+each atom is determined by which element it is, which in turn is
+specified by the element-to-type mapping specified by the "dump_modify
+element" command. By default every atom type is C (carbon). Every
+element has a diamtere associated with it, which is the same as used
+by the "AtomEye"_atomeye visualization package.
+
+If {radius} or {shape} is specified for the diam value then those the
+atom style you are using must define those attributes. The radius or
+shape of the individual atom is then used to draw it. Currently, only
+spherical shapes are allowed. Support for ellipsoids will be added
+later.
+
+An atom-attribute can also be used for the diam value. Any attribute
+listed on the "dump custom"_dump.html doc page can be used, e.g. vx,
+fy, q, spin, etc. This includes per-atom quantities calculated by a
+"compute"_compute.html, "fix"_fix.html, or "variable"_variable.html.
+For example, if "vx" is used as the per-atom attribute, then the
+diameter of the atom will depend on the x-component of its velocity,
+which will assumed to be >= 0.0, else the atom will not be drawn.
+
+:line
+
+The {bond} keyword determines the color and thickness or diameter of
+bonds rendered in the image. If {none} is specified for the color
+value (with any diam value), then no bonds are drawn.
+
+If {atom} is specified for the color value, then the each bond is
+drawn in 2 halves, with the color of each half being the color of the
+atom at that end of the bond.
+
+If {type} is specified for the color value, then the color of each
+bond is determined by its bond type. By default the mapping of types
+to colors is as follows:
+
+type 1 = red
+type 2 = green
+type 3 = blue
+type 4 = yellow
+type 5 = aqua
+type 6 = cyan :ul
+
+and repeats itself for types > 6. This mapping can be changed by the
+"dump_modify bcolor"_dump_modify.html command.
+
+The diam value can be a numeric value {D} or {type}.
+
+If a numeric value {D} is specified, then all bond will be drawn with
+that diameter, e.g. 1.0, which is in distance units in whatever
+"units"_units.html you are using, e.g. Angstroms.
+
+If {type} is specified for the diam value then the color of each bond
+is determined by its bond type. By default all types have diameter
+0.5. This mapping can be changed by the "dump_modify
+bdiam"_dump_modify.html command.
+
+:line
+
+The {size} keyword determines the width and height of the created
+image files, in numbers of pixels in each direction.
+
+:line
+
+The {view}, {center}, {up}, {zoom}, and {persp} settings determine how
+3d simulation space is mapped to the 2d plane of the image. Basically
+they control how the simulation box appears in the image.
+
+All of the {view}, {center}, {up}, {zoom}, and {persp} settings can be
+specified as numeric values, whose meaning is explained below. But
+any of them can also be specified as an equal-style variable, by using
+v_name as the setting, where "name" is the variable name. In this
+case the variable will be evaluated on the timestep each image is
+created to create a new setting. If the equal-style variable is
+time-dependent, this is a means of changing the way the simulation box
+appears from image to image, effectively doing a pan or fly-by view of
+your simulation.
+
+The {view} keyword determines the viewpoint from which the simulation
+box is viewed. The {theta} setting is the vertical angle from the +z
+axis, and must be an angle from 0 to 180 degrees. The {phi} setting
+is an azimuthal angle around the z axis and can be positive or
+negative.
+
+The {center} keyword determines the point in simulation space that
+will be at the center of the image. {Cx}, {Cy}, and {Cz} are
+speficied as fractions of the box dimensions, so that (0.5,0.5,0.5) is
+the center of the simulation box. These values do not have to be
+between 0.0 and 1.0, if you want the simulation box to be offset from
+the center of the image. Note, however, that if you choose odd values
+for {Cx}, {Cy}, or {Cz} you may get a blank image. Internally, {Cx},
+{Cy}, and {Cz} are converted into a point in simulation space. If
+{flag} is set to "s" for static, then this conversion is done once, at
+the time the dump command is issued. If {flag} is set to "d" for
+dynamic then the conversion is performed every time a new image is
+created. If the box size or shape is changing, this will adjust the
+center point in simulation space.
+
+The {up} keyword determines what direction in simulation space will be
+"up" in the image. Internally it is stored as a vector that is in the
+plane perpendicular to the view vector implied by the {theta} and
+{pni} settings, and which is in the plane defined by the view vector
+and user-specified up vector. Thus this internal vector is computed
+from the user-specified {up} vector as
+
+up_internal = view cross (up cross view) :pre
+
+This means the only restriction on the specified {up} vector is that
+it cannot be parallel to the {view} vector, implied by the {theta} and
+{phi} settings.
+
+The {zoom} keyword scales the size of the simulation box as it appears
+in the image. The default {factor} setting of 1 should display an
+image mostly filled by the atoms in the simulation box. A {factor} >
+1 will make the simulation box larger; a {factor} < 1 will make it
+smaller.
+
+The {persp} keyword how much depth perspective is present in the
+image. Depth persepctive makes lines that are parallel in simulation
+space appear non-parallel in the image. A {factor} setting of 0.0
+means that parallel lines will meet at infininty (1.0/factor), which
+is an orthographic rendering with no persepctive. A {factor} setting
+between 0.0 and 1.0 will introduce more perspective. A {factor} > 1
+will create a highly skewed image with a large amount of perspective.
+
+The {dynamic} keyword
+determines the color and thickness of bonds
+rendered in the image.
+
+:line
+
+The {box} keyword determines how the simulation box boundaries are
+rendered as thin cylinders in the image. If {no} is set, then the box
+boundaries are not drawn and the {diam} setting is ignored. If {yes}
+is set, the 12 edges of the box are drawn, with a diameter that is a
+fraction of the shortest box lenght in x, y, or z. The color of the
+box boundaires can be set with the "dump_modify
+boxcolor"_dump_modify.html command.
+
+The {axes} keyword determines how the coordinate axes are rendered as
+thin cylinders in the image. If {no} is set, then the axes are not
+drawn and the {length} and {diam} settings are ignored. If {yes} is
+set, 3 thin cylinders are drawn to represent the x,y,z axes in colors
+red,green/blue. The origin of these cylinders will be offset
+from the lower left corner of the box by 10%. The {length} setting
+determines how long the cylinders will be. The {diam} setting
+determines their thickness.
+
+:line
+
+The {shiny} keyword determines how shiny the objects rendered in the
+image will appear. This must be a value 0.0 <= S <= 1.0, where S = 1
+is a highly-reflective surface and S = 0 is a rough non-shiny surface.
+
+The {ssao} keyword turns on/off a screen space ambient occlusion
+(SSAO) model for depth shading. If {yes} is set, then atoms further
+away from the viewer are darkened, which is perceived as depth by the
+viewer. The calculation of this effect can increase the cost of
+computing the image by roughly 2x. If {no} is set, the depth shading
+is not performed.
+
+:line
+
+A series of JPG or PPM images can be converted into a movie file and
+then played as a movie using commonly available tools.
+
+Convert JPG or PPM files into an animated GIF or MPEG or other movie
+file:
+
+a) Use the ImageMagick convert program. :ulb,l
+
+% convert *.jpg foo.gif
+% convert *.jpg foo.mpg :pre
+
+b) Use QuickTime. :l
+
+Select "Open Image Sequence" under the File menu
+Load the images into QuickTime
+Select "Export" under the File menu
+Save the movie as a QuickTime movie (*.mov) or in another format
+
+c) Windows-based tool. :ule,l
+
+If someone tells us how to do this a common Windows-based tool, we'll
+post the instructions here.
+
+Play the movie:
+
+a) Use your browser to view an animated GIF movie. :ulb,l
+
+Select "Open File" under the File menu
+Load the animated GIF file
+
+b) Use the freely available mplayer tool to view an MPEG movie. :l
+
+% mplayer foo.mpg :pre
+
+c) Use the "Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html
+"animate tool"_http://www.sandia.gov/~sjplimp/pizza/doc/animate.html,
+which works directly on a series of image files. :l
+
+a = animate("foo*.jpg") :pre
+
+d) QuickTime and other Windows-based media players can
+obviously play movie files directly. :ule,l
+
+:line
+
+See "this section"_Section_modify.html of the manual for information
+on how to add new compute and fix styles to LAMMPS to calculate
+per-atom quantities which could then be output into dump files.
+
+:line
+
+[Restrictions:]
+
+To write JPG images, you must link LAMMPS with a JPEG library - see
+the "Making LAMMPS"_Section_start.html#2_2_4 section of the
+documentation for details.
+
+[Related commands:]
+
+"dump"_dump.html, "dump_modify"_dump_modify.html, "undump"_undump.html
+
+[Default:]
+
+The defaults for the keywords are as follows:
+
+atom = type 1.0
+bond = none 0.0 (if no bonds in system)
+bond = atom 0.5 (if bonds in system)
+size = 512 512
+view = 60 30 (for 3d)
+view = 0 0 (for 2d)
+center = s 0.5 0.5 0.5
+up = 0 0 1 (for 3d)
+up = 0 1 0 (for 2d)
+zoom = 1.0
+persp = 0.0
+dynamic = no
+box = yes 0.01
+axes = no 0.0 0.0
+shiny = 1.0
+ssao = no :ul
diff --git a/doc/dump_modify.html b/doc/dump_modify.html
index 21f094375..aad55efb1 100644
--- a/doc/dump_modify.html
+++ b/doc/dump_modify.html
@@ -1,250 +1,569 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>dump_modify command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>dump_modify dump-ID keyword values ...
</PRE>
<UL><LI>dump-ID = ID of dump to modify
<LI>one or more keyword/value pairs may be appended
-<LI>keyword = <I>append</I> or <I>every</I> or <I>flush</I> or <I>format</I> or <I>image</I> or <I>label</I> or <I>precision</I> or <I>region</I> or <I>scale</I> or <I>sort</I> or <I>thresh</I> or <I>unwrap</I>
+<LI>keyword = <I>acolor</I> or <I>adiam</I> or <I>amap</I> or <I>append</I> or <I>bcolor</I> or <I>bdiam</I> or <I>bgcolor</I> or <I>boxcolor</I> or <I>color</I> or <I>every</I> or <I>flush</I> or <I>format</I> or <I>image</I> or <I>label</I> or <I>precision</I> or <I>region</I> or <I>scale</I> or <I>sort</I> or <I>thresh</I> or <I>unwrap</I>
-<PRE> <I>append</I> arg = <I>yes</I> or <I>no</I>
+<PRE> <I>acolor</I> args = type color
+ type = atom type or range of types (see below)
+ color = name of color or color1/color2/...
+ <I>adiam</I> args = type diam
+ type = atom type or range of types (see below)
+ diam = diameter of atoms of that type (distance units)
+ <I>amap</I> args = lo hi style N delta entry1 entry2 ... entryN
+ lo = number or <I>min</I> = lower bound of range of color map
+ hi = number or <I>max</I> = upper bound of range of color map
+ style = 2 letters = "b" or "c" or "s" plus "a" or "f"
+ "c" for continuous
+ "d" for discrete
+ "s" for sequential
+ "a" for absolute
+ "f" for fractional
+ delta = binsize (only used for style "s" = sequential)
+ binsize = range is divided into bins of this width
+ N = # of subsequent entries
+ entry = value color (for continuous style)
+ value = number or <I>min</I> or <I>max</I> = single value within range
+ color = name of color used for that value
+ entry = lo hi color (for discrete style)
+ lo/hi = number or <I>min</I> or <I>max</I> = lower/upper bound of subset of range
+ color = name of color used for that value
+ entry = color (for sequential style)
+ color = name of color used for a bin within range
+ <I>append</I> arg = <I>yes</I> or <I>no</I>
+ <I>bcolor</I> args = type color
+ type = bond type or range of types (see below)
+ color = name of color or color1/color2/...
+ <I>bdiam</I> args = type diam
+ type = bond type or range of types (see below)
+ diam = diameter of bonds of that type (distance units)
+ <I>bgcolor</I> arg = color
+ color = name of color for background
+ <I>boxcolor</I> arg = color
+ color = name of color for box lines
+ <I>color</I> args = name R G B
+ name = name of color
+ R,G,B = red/green/blue numeric values from 0.0 to 1.0
<I>element</I> args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
<I>every</I> arg = N
N = dump every this many timesteps
N can be a variable (see below)
<I>first</I> arg = <I>yes</I> or <I>no</I>
<I>format</I> arg = C-style format string for one line of output
<I>flush</I> arg = <I>yes</I> or <I>no</I>
<I>image</I> arg = <I>yes</I> or <I>no</I>
<I>label</I> arg = string
string = character string (e.g. BONDS) to use in header of dump local file
<I>pad</I> arg = Nchar = # of characters to convert timestep to
<I>precision</I> arg = power-of-10 value from 10 to 1000000
<I>region</I> arg = region-ID or "none"
<I>scale</I> arg = <I>yes</I> or <I>no</I>
<I>sort</I> arg = <I>off</I> or <I>id</I> or N or -N
off = no sorting of per-atom lines within a snapshot
id = sort per-atom lines by atom ID
N = sort per-atom lines in ascending order by the Nth column
-N = sort per-atom lines in descending order by the Nth column
<I>thresh</I> args = attribute operation value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operation = "<" or "<=" or ">" or ">=" or "==" or "!="
value = numeric value to compare to
these 3 args can be replaced by the word "none" to turn off thresholding
<I>unwrap</I> arg = <I>yes</I> or <I>no</I>
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>dump_modify 1 format "%d %d %20.15g %g %g" scale yes
dump_modify myDump image yes scale no flush yes
dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2
dump_modify xtcdump precision 10000
dump_modify 1 every 1000
dump_modify 1 every v_myVar
</PRE>
+<P>NOTE: add some image examples
+</P>
<P><B>Description:</B>
</P>
<P>Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.
</P>
+<HR>
+
+<P>The <I>acolor</I> keyword applies only to the dump <I>image</I> style. It can
+be used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>atom</I>
+keyword, when its color setting is <I>type</I>, to set the color that atoms
+of each type will be drawn in the image.
+</P>
+<P>The specified <I>type</I> should be an integer from 1 to Ntypes = the
+number of atom types. A wildcard asterisk can be used in place of or
+in conjunction with the <I>type</I> argument to specify a range of atom
+types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
+number of atom types, then an asterisk with no numeric values means
+all types from 1 to N. A leading asterisk means all types from 1 to n
+(inclusive). A trailing asterisk means all types from n to N
+(inclusive). A middle asterisk means all types from m to n
+(inclusive).
+</P>
+<P>The specified <I>color</I> can be a single color which is any of the 140
+pre-defined colors (see below) or a colorname defined by the
+dump_modify color option. Or it can be two or more colors separated
+by a "/" character, e.g. red/green/blue. In the former case, that
+color is assigned to all the specified atom types. In the latter
+case, the list of colors are assigned in a round-robin fashion
+to each of the specified atom types.
+</P>
+<HR>
+
+<P>The <I>adiam</I> keyword applies only to the dump <I>image</I> style. It can be
+used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>atom</I>
+keyword, when its diam setting is <I>type</I>, to set the size that atoms
+of each type will be drawn in the image. The specified <I>type</I> should
+be an integer from 1 to Ntypes. As with the <I>acolor</I> keyword, a
+wildcard asterisk can be used as part of the <I>type</I> argument to
+specify a range of atomt types. The specified <I>diam</I> is the size in
+whatever distance <A HREF = "units.html">units</A> you are using, e.g. Angstroms.
+</P>
+<HR>
+
+<P>The <I>amap</I> keyword applies only to the dump <I>image</I> style. It can be
+used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>atom</I>
+keyword, when its atom setting is an atom-attribute, to setup a color
+map. The color map is used to assign a specific RGB (red/green/blue)
+color value to an individual atom when it is drawn, based on the
+atom's attribute, which is a numeric value, e.g. its x-component of
+velocity if the atom-attribute "vx" was specified.
+</P>
+<P>The basic idea of a color map is that the atom-attribute will be
+within a range of values, and that range is associated with a a series
+of colors (e.g. red, blue, green). An atom's specific value (vx =
+-3.2) can then mapped to the series of colors (e.g. halfway between
+red and blue), and a specific color is determined via an interpolation
+procedure. There are other options for the mapping mechanism, all of
+which are explained on the <A HREF = "dump_modify.html">dump_modify</A> doc page.
+</P>
+<P>There are many possible options for the color map, enabled by the
+<I>amap</I> keyword. Here are the details.
+</P>
+<P>The <I>lo</I> and <I>hi</I> settings determine the range of values allowed for
+the atom attribute. If numeric values are used for <I>lo</I> and/or <I>hi</I>,
+then values that are lower/higher than that value are set to the
+value. I.e. the range is static. If <I>lo</I> is specified as <I>min</I> or
+<I>hi</I> as <I>max</I> then the range is dynamic, and will the lower and/or
+upper bound will be calculated each time an image is drawn.
+</P>
+<P>The <I>style</I> setting is two letters, such as "ca". The first letter is
+either "c" for continuous, "d" for discrete, or "s" for sequential.
+The second letter is either "a" for absolute, or "f" for fractional.
+</P>
+<P>A continuous color map is one in which the color changes continuously
+from value to value within the range. A discrete color map is one in
+which discrete colors are assigned to sub-ranges of values within the
+range. A sequential color map is one in which discrete colors are
+assigned to a sequence of sub-ranges of values covering the entire
+range.
+</P>
+<P>An absolute color map is one in which the values to which colors are
+assigned are specified explicitly as values within the range. A
+fractional color map is one in which the values to which colors are
+assigned are specified as a fractional portion of the range. For
+example if the range is from -10.0 to 10.0, and the color red is to be
+assigned to atoms with a value of 5.0, then for an absolute color map
+the number 5.0 would be used. But for a fractional map, the number
+0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
+</P>
+<P>The <I>delta</I> setting is only specified if the style is sequential. It
+specifies the bin size to use within the range for assigning
+consecutive colors to. For example, if the range is from -10.0 to
+10.0 and a <I>delta</I> of 1.0 is used, then 20 colors will be assigned to
+the range. The first will be from -10.0 <= color1 < -9.0, then 2nd
+from -9.0 <= color2 < -8.0, etc.
+</P>
+<P>The <I>N</I> setting is how many entries follow. The format of the entries
+depends on whether the color map style is continuous, discrete or
+sequential. In all cases the <I>color</I> setting can be any of the 140
+pre-defined colors (see below) or a colorname defined by the
+dump_modify color option.
+</P>
+<P>For continuous color maps, each entry has a <I>value</I> and a <I>color</I>.
+The <I>value</I> is either a number within the range of values or <I>min</I> or
+<I>max</I>. The <I>value</I> of the first entry must be <I>min</I> and the <I>value</I>
+of hte last entry must be <I>max</I>. Any entries in between must have
+increasing values. Note that numeric values can be specified either
+as absolute numbers or as fractions (0.0 to 1.0) of the range,
+depending on the "a" or "f" in the style setting for the color map.
+</P>
+<P>Here is how the entries are used to determine the color of an
+individual atom, given the value X of its atom attribute. X will fall
+between 2 of the entry values. The color of the atom is linearly
+interpolated (in each of the RGB values) between the 2 colors
+associated with those entries. For example, if X = -5.0 and the 2
+surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
+atom's color will be halfway between "red" and "blue", which happens
+to be "purple".
+</P>
+<P>For discrete color maps, each entry has a <I>lo</I> and <I>hi</I> value and a
+<I>color</I>. The <I>lo</I> and <I>hi</I> settings are either numbers within the
+range of values or <I>lo</I> can be <I>min</I> or <I>hi</I> can be <I>max</I>. The <I>lo</I>
+and <I>hi</I> settings of the last entry must be <I>min</I> and <I>max</I>. Other
+entries can have any <I>lo</I> and <I>hi</I> values, including sub-ranges of
+values that overlap. Note that numeric <I>lo</I> and <I>hi</I> values can be
+specified either as absolute numbers or as fractions (0.0 to 1.0) of
+the range, depending on the "a" or "f" in the style setting for the
+color map.
+</P>
+<P>Here is how the entries are used to determine the color of an
+individual atom, given the value X of its atom attribute. The entries
+are scanned from first to last. The first time that <I>lo</I> <= X <=
+<I>hi</I>, X is assigned the color associated with that entry. You can
+think of the last entry as assigning a default color (since it will
+always be matched by X), and the earlier entries as colors that
+override the default. Also note that no interpolation of a color RGB
+is done. All atoms will be drawn with one of the colors in the list
+of entries.
+</P>
+<P>For sequential color maps, each entry has only a <I>color</I>. Here is how
+the entries are used to determine the color of an individual atom,
+given the value X of its atom attribute. The range is partitioned
+into N bins of width <I>binsize</I>. Thus X will fall in a specific bin
+from 1 to N, say the Mth bin. If it falls on a boundary between 2
+bins, it is considered to be in the higher of the 2 bins. Each bin is
+assigned a color from the E entries. If E < N, then the colors are
+repeated. For example if 2 entries with colors red and green are
+specified, then the odd numbered bins will be red and the even bins
+green. The color of the atom is the color of its bin. Note that the
+sequential color map is really a shorthand way of defining a discrete
+color map without having to specify where all the bin boundaries are.
+</P>
+<HR>
+
<P>The <I>append</I> keyword applies to all dump styles except <I>cfg</I> and <I>xtc</I>
and <I>dcd</I>. It also applies only to text output files, not to binary
or gzipped files. If specified as <I>yes</I>, then dump snapshots are
appended to the end of an existing dump file. If specified as <I>no</I>,
then a new dump file will be created which will overwrite an existing
file with the same name. This keyword can only take effect if the
dump_modify command is used after the <A HREF = "dump.html">dump</A> command, but
before the first command that causes dump snapshots to be output,
e.g. a <A HREF = "run.html">run</A> or <A HREF = "minimize.html">minimize</A> command. Once the
dump file has been opened, this keyword has no further effect.
</P>
-<P>The <I>element</I> keyword applies only to the the dump <I>cfg</I> style. It
-associates element names (e.g. H, C, Fe) with LAMMPS atom types, so
-that the <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A>
-visualization package can render atoms with the appropriate size and
-color. An element name is specified for each atom type (1 to Ntype)
-in the simulation. The same element name can be given to multiple
-atom types.
+<HR>
+
+<P>The <I>bcolor</I> keyword applies only to the dump <I>image</I> style. It can
+be used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>bond</I>
+keyword, when its color setting is <I>type</I>, to set the color that bonds
+of each type will be drawn in the image.
</P>
+<P>The specified <I>type</I> should be an integer from 1 to Nbondtypes = the
+number of bond types. A wildcard asterisk can be used in place of or
+in conjunction with the <I>type</I> argument to specify a range of bond
+types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
+number of bond types, then an asterisk with no numeric values means
+all types from 1 to N. A leading asterisk means all types from 1 to n
+(inclusive). A trailing asterisk means all types from n to N
+(inclusive). A middle asterisk means all types from m to n
+(inclusive).
+</P>
+<P>The specified <I>color</I> can be a single color which is any of the 140
+pre-defined colors (see below) or a colorname defined by the
+dump_modify color option. Or it can be two or more colors separated
+by a "/" character, e.g. red/green/blue. In the former case, that
+color is assigned to all the specified bond types. In the latter
+case, the list of colors are assigned in a round-robin fashion to each
+of the specified bond types.
+</P>
+<HR>
+
+<P>The <I>bdiam</I> keyword applies only to the dump <I>image</I> style. It can be
+used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>bond</I>
+keyword, when its diam setting is <I>type</I>, to set the diameter that
+bonds of each type will be drawn in the image. The specified <I>type</I>
+should be an integer from 1 to Nbondtypes. As with the <I>bcolor</I>
+keyword, a wildcard asterisk can be used as part of the <I>type</I>
+argument to specify a range of bond types. The specified <I>diam</I> is
+the size in whatever distance <A HREF = "units.html">units</A> you are using,
+e.g. Angstroms.
+</P>
+<HR>
+
+<P>The <I>bgcolor</I> keyword applies only to the dump <I>image</I> style. It sets
+the background color of each image. The color name can be any of the
+140 pre-defined colors (see below) or a colorname defined by the
+dump_modify color option.
+</P>
+<HR>
+
+<P>The <I>boxcolor</I> keyword applies only to the dump <I>image</I> style. It
+sets the color of the simulation box drawn around the atoms in each
+image. See the "dump image box" command for how to specify that a box
+be drawn. The color name can be any of the 140 pre-defined colors
+(see below) or a colorname defined by the dump_modify color option.
+</P>
+<HR>
+
+<P>The <I>element</I> keyword applies only to the the dump <I>cfg</I> and <I>image</I>
+styles. It associates element names (e.g. H, C, Fe) with LAMMPS atom
+types. In the case of dump <I>cfg</I>, it allows the <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A>
+visualization package to read the dump file and render atoms with the
+appropriate size and color. In the case of dump <I>image</I>, the output
+images will follow the same <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> convention. An element
+name is specified for each atom type (1 to Ntype) in the simulation.
+The same element name can be given to multiple atom types.
+</P>
+
+
+<HR>
+
<P>The <I>every</I> keyword changes the dump frequency originally specified by
the <A HREF = "dump.html">dump</A> command to a new value. The every keyword can be
specified in one of two ways. It can be a numeric value in which case
it must be > 0. Or it can be an <A HREF = "variable.html">equal-style variable</A>,
which should be specified as v_name, where name is the variable name.
In this case, the variable is evaluated at the beginning of a run to
determine the next timestep at which a dump snapshot will be written
out. On that timestep, the variable will be evaluated again to
determine the next timestep, etc. Thus the variable should return
timestep values. See the stagger() and logfreq() math functions for
<A HREF = "variable.html">equal-style variables</A>, as examples of useful functions
to use in this context. Other similar math functions could easily be
added as options for <A HREF = "variable.html">equal-style variables</A>. When
using the variable option with the <I>every</I> keyword, you also need to
use the <I>first</I> option if you want an initial snapshot written to the
dump file. The <I>every</I> keyword cannot be used with the dump <I>dcd</I>
style.
</P>
<P>For example, the following commands will
write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
</P>
<PRE>variable s equal logfreq(10,3,10)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes
</PRE>
+<HR>
+
<P>The <I>first</I> keyword determines whether a dump snapshot is written on
the very first timestep after the dump command is invoked. This will
always occur if the current timestep is a multiple of N, the frequency
specified in the <A HREF = "dump.html">dump</A> command, including timestep 0. But
if this is not the case, a dump snapshot will only be written if the
setting of this keyword is <I>yes</I>. If it is <I>no</I>, which is the
default, then it will not be written.
</P>
+<HR>
+
<P>The <I>flush</I> keyword determines whether a flush operation is invoked
after a dump snapshot is written to the dump file. A flush insures
the output in that file is current (no buffering by the OS), even if
LAMMPS halts before the simulation completes. Flushes cannot be
performed with dump style <I>xtc</I>.
</P>
<P>The text-based dump styles have a default C-style format string which
simply specifies %d for integers and %g for real values. The <I>format</I>
keyword can be used to override the default with a new C-style format
string. Do not include a trailing "\n" newline character in the
format string. This option has no effect on the <I>dcd</I> and <I>xtc</I> dump
styles since they write binary files. Note that for the <I>cfg</I> style,
the first two fields (atom id and type) are not actually written into
the CFG file, though you must include formats for them in the format
string.
</P>
+<HR>
+
<P>The <I>image</I> keyword applies only to the dump <I>atom</I> style. If the
image value is <I>yes</I>, 3 flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
example, an x image flag of -2 with a normalized coord of 0.5 means
the atom is in the center of the box, but has passed thru the box
boundary 2 times and is really 2 box lengths to the left of its
current coordinate. Note that for dump style <I>custom</I> these various
values can be printed in the dump file by using the appropriate atom
attributes in the dump command itself.
</P>
+<HR>
+
<P>The <I>label</I> keyword applies only to the dump <I>local</I> style. When
it writes local informatoin, such as bond or angle topology
to a dump file, it will use the specified <I>label</I> to format
the header. By default this includes 2 lines:
</P>
<PRE>ITEM: NUMBER OF ENTRIES
ITEM: ENTRIES ...
</PRE>
<P>The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
</P>
+<HR>
+
<P>The <I>pad</I> keyword only applies when the dump filename is specified
with a wildcard "*" character which becomes the timestep. If <I>pad</I> is
0, which is the default, the timestep is converted into a string of
unpadded length, e.g. 100 or 12000 or 2000000. When <I>pad</I> is
specified with <I>Nchar</I> > 0, the string is padded with leading zeroes
so they are all the same length = <I>Nchar</I>. For example, pad 7 would
yield 0000100, 0012000, 2000000. This can be useful so that
post-processing programs can easily read the files in ascending
timestep order.
</P>
+<HR>
+
<P>The <I>precision</I> keyword only applies to the dump <I>xtc</I> style. A
specified value of N means that coordinates are stored to 1/N
nanometer accuracy, e.g. for N = 1000, the coordinates are written to
1/1000 nanometer accuracy.
</P>
-<P>The <I>region</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I>
-styles. If specified, only atoms in the region will be written to the
-dump file. Only one region can be applied as a filter (the last one
-specified). See the <A HREF = "region.html">region</A> command for more details.
-Note that a region can be defined as the "inside" or "outside" of a
-geometric shape, and it can be the "union" or "intersection" of a
-series of simpler regions.
+<HR>
+
+<P>The <I>region</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I> and
+<I>image</I> styles. If specified, only atoms in the region will be
+written to the dump file or included in the image. Only one region
+can be applied as a filter (the last one specified). See the
+<A HREF = "region.html">region</A> command for more details. Note that a region can
+be defined as the "inside" or "outside" of a geometric shape, and it
+can be the "union" or "intersection" of a series of simpler regions.
</P>
+<HR>
+
<P>The <I>scale</I> keyword applies only to the dump <I>atom</I> style. A scale
value of <I>yes</I> means atom coords are written in normalized units from
0.0 to 1.0 in each box dimension. If the simluation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. A
value of <I>no</I> means they are written in absolute distance units
(e.g. Angstroms or sigma).
</P>
+<HR>
+
<P>The <I>sort</I> keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of <I>off</I> means they will
typically be written in indeterminate order, either in serial or
parallel. This is the case even in serial if the <A HREF = "atom_modify.html">atom_modify
sort</A> option is turned on, which it is by default, to
improve performance. A sort value of <I>id</I> means sort the output by
atom ID. A sort value of N or -N means sort the output by the value
in the Nth column of per-atom info in either ascending or descending
order. The dump <I>local</I> style cannot be sorted by atom ID, since
there are typically multiple lines of output per atom. Some dump
styles, such as <I>dcd</I> and <I>xtc</I>, require sorting by atom ID to format
the output file correctly.
</P>
<P>IMPORTANT NOTE: Unless it is required by the dump style, sorting dump
file output requires extra overhead in terms of CPU and communication
cost, as well as memory, versus unsorted output.
</P>
-<P>The <I>thresh</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I>
-styles. Multiple thresholds can be specified. Specifying "none"
-turns off all threshold criteria. If thresholds are specified, only
-atoms whose attributes meet all the threshold criteria are written to
-the dump file. The possible attributes that can be tested for are the
-same as those that can be specified in the <A HREF = "dump.html">dump custom</A>
-command. Note that different attributes can be output by the dump
-custom command than are used as threshold criteria by the dump_modify
-command. E.g. you can output the coordinates and stress of atoms
-whose energy is above some threshold.
+<HR>
+
+<P>The <I>thresh</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I> and
+<I>image</I> styles. Multiple thresholds can be specified. Specifying
+"none" turns off all threshold criteria. If thresholds are specified,
+only atoms whose attributes meet all the threshold criteria are
+written to the dump file or included in the image. The possible
+attributes that can be tested for are the same as those that can be
+specified in the <A HREF = "dump.html">dump custom</A> command. Note that different
+attributes can be output by the dump custom command than are used as
+threshold criteria by the dump_modify command. E.g. you can output
+the coordinates and stress of atoms whose energy is above some
+threshold.
</P>
+<HR>
+
<P>The <I>unwrap</I> keyword only applies to the dump <I>dcd</I> and <I>xtc</I> styles.
If set to <I>yes</I>, coordinates will be written "unwrapped" by the image
flags for each atom. Unwrapped means that if the atom has passed thru
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that these coordinates may thus be far outside the
box size stored with the snapshot.
</P>
+<HR>
+
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
-<P><A HREF = "dump.html">dump</A>, <A HREF = "undump.html">undump</A>
+<P><A HREF = "dump.html">dump</A>, <A HREF = "dump_image.html">dump image</A>, <A HREF = "undump.html">undump</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are
</P>
-<UL><LI>append = no
+<UL><LI>acolor = * red/green/blue/yellow/aqua/cyan
+<LI>adiam = * 1.0
+<LI>amap = min max cf 2 0.0 blue 1.0 red
+<LI>append = no
+<LI>bgcolor = black
+<LI>boxcolor = yellow
+<LI>color = 140 color names are pre-defined as listed below
<LI>element = "C" for every atom type
<LI>every = whatever it was set to via the <A HREF = "dump.html">dump</A> command
<LI>first = no
-<LI>flush = yes (except for the dump <I>xtc</I> style)
+<LI>flush = yes
<LI>format = %d and %g for each integer or floating point value
<LI>image = no
<LI>label = ENTRIES
<LI>pad = 0
<LI>precision = 1000
<LI>region = none
<LI>scale = yes
<LI>sort = off for dump styles <I>atom</I>, <I>custom</I>, <I>cfg</I>, and <I>local</I>
<LI>sort = id for dump styles <I>dcd</I>, <I>xtc</I>, and <I>xyz</I>
<LI>thresh = none
<LI>unwrap = no
</UL>
+<HR>
+
+<P>These are the 140 colors that LAMMPS pre-defines for use with the
+<A HREF = "dump_image.html">dump image</A> and dump_modify commands. Additional
+colors can be defined with the dump_modify color command. The 3
+numbers listed for each name are the RGB (red/green/blue) values.
+Divide each value by 255 to get the equivalent 0.0 to 1.0 value.
+</P>
+<DIV ALIGN=center><TABLE BORDER=1 >
+<TR><TD >aliceblue = 240, 248, 255 </TD><TD >antiquewhite = 250, 235, 215 </TD><TD >aqua = 0, 255, 255 </TD><TD >aquamarine = 127, 255, 212 </TD><TD >azure = 240, 255, 255 </TD></TR>
+<TR><TD >beige = 245, 245, 220 </TD><TD >bisque = 255, 228, 196 </TD><TD >black = 0, 0, 0 </TD><TD >blanchedalmond = 255, 255, 205 </TD><TD >blue = 0, 0, 255 </TD></TR>
+<TR><TD >blueviolet = 138, 43, 226 </TD><TD >brown = 165, 42, 42 </TD><TD >burlywood = 222, 184, 135 </TD><TD >cadetblue = 95, 158, 160 </TD><TD >chartreuse = 127, 255, 0 </TD></TR>
+<TR><TD >chocolate = 210, 105, 30 </TD><TD >coral = 255, 127, 80 </TD><TD >cornflowerblue = 100, 149, 237 </TD><TD >cornsilk = 255, 248, 220 </TD><TD >crimson = 220, 20, 60 </TD></TR>
+<TR><TD >cyan = 0, 255, 255 </TD><TD >darkblue = 0, 0, 139 </TD><TD >darkcyan = 0, 139, 139 </TD><TD >darkgoldenrod = 184, 134, 11 </TD><TD >darkgray = 169, 169, 169 </TD></TR>
+<TR><TD >darkgreen = 0, 100, 0 </TD><TD >darkkhaki = 189, 183, 107 </TD><TD >darkmagenta = 139, 0, 139 </TD><TD >darkolivegreen = 85, 107, 47 </TD><TD >darkorange = 255, 140, 0 </TD></TR>
+<TR><TD >darkorchid = 153, 50, 204 </TD><TD >darkred = 139, 0, 0 </TD><TD >darksalmon = 233, 150, 122 </TD><TD >darkseagreen = 143, 188, 143 </TD><TD >darkslateblue = 72, 61, 139 </TD></TR>
+<TR><TD >darkslategray = 47, 79, 79 </TD><TD >darkturquoise = 0, 206, 209 </TD><TD >darkviolet = 148, 0, 211 </TD><TD >deeppink = 255, 20, 147 </TD><TD >deepskyblue = 0, 191, 255 </TD></TR>
+<TR><TD >dimgray = 105, 105, 105 </TD><TD >dodgerblue = 30, 144, 255 </TD><TD >firebrick = 178, 34, 34 </TD><TD >floralwhite = 255, 250, 240 </TD><TD >forestgreen = 34, 139, 34 </TD></TR>
+<TR><TD >fuchsia = 255, 0, 255 </TD><TD >gainsboro = 220, 220, 220 </TD><TD >ghostwhite = 248, 248, 255 </TD><TD >gold = 255, 215, 0 </TD><TD >goldenrod = 218, 165, 32 </TD></TR>
+<TR><TD >gray = 128, 128, 128 </TD><TD >green = 0, 128, 0 </TD><TD >greenyellow = 173, 255, 47 </TD><TD >honeydew = 240, 255, 240 </TD><TD >hotpink = 255, 105, 180 </TD></TR>
+<TR><TD >indianred = 205, 92, 92 </TD><TD >indigo = 75, 0, 130 </TD><TD >ivory = 255, 240, 240 </TD><TD >khaki = 240, 230, 140 </TD><TD >lavender = 230, 230, 250 </TD></TR>
+<TR><TD >lavenderblush = 255, 240, 245 </TD><TD >lawngreen = 124, 252, 0 </TD><TD >lemonchiffon = 255, 250, 205 </TD><TD >lightblue = 173, 216, 230 </TD><TD >lightcoral = 240, 128, 128 </TD></TR>
+<TR><TD >lightcyan = 224, 255, 255 </TD><TD >lightgoldenrodyellow = 250, 250, 210 </TD><TD >lightgreen = 144, 238, 144 </TD><TD >lightgrey = 211, 211, 211 </TD><TD >lightpink = 255, 182, 193 </TD></TR>
+<TR><TD >lightsalmon = 255, 160, 122 </TD><TD >lightseagreen = 32, 178, 170 </TD><TD >lightskyblue = 135, 206, 250 </TD><TD >lightslategray = 119, 136, 153 </TD><TD >lightsteelblue = 176, 196, 222 </TD></TR>
+<TR><TD >lightyellow = 255, 255, 224 </TD><TD >lime = 0, 255, 0 </TD><TD >limegreen = 50, 205, 50 </TD><TD >linen = 250, 240, 230 </TD><TD >magenta = 255, 0, 255 </TD></TR>
+<TR><TD >maroon = 128, 0, 0 </TD><TD >mediumaquamarine = 102, 205, 170 </TD><TD >mediumblue = 0, 0, 205 </TD><TD >mediumorchid = 186, 85, 211 </TD><TD >mediumpurple = 147, 112, 219 </TD></TR>
+<TR><TD >mediumseagreen = 60, 179, 113 </TD><TD >mediumslateblue = 123, 104, 238 </TD><TD >mediumspringgreen = 0, 250, 154 </TD><TD >mediumturquoise = 72, 209, 204 </TD><TD >mediumvioletred = 199, 21, 133 </TD></TR>
+<TR><TD >midnightblue = 25, 25, 112 </TD><TD >mintcream = 245, 255, 250 </TD><TD >mistyrose = 255, 228, 225 </TD><TD >moccasin = 255, 228, 181 </TD><TD >navajowhite = 255, 222, 173 </TD></TR>
+<TR><TD >navy = 0, 0, 128 </TD><TD >oldlace = 253, 245, 230 </TD><TD >olive = 128, 128, 0 </TD><TD >olivedrab = 107, 142, 35 </TD><TD >orange = 255, 165, 0 </TD></TR>
+<TR><TD >orangered = 255, 69, 0 </TD><TD >orchid = 218, 112, 214 </TD><TD >palegoldenrod = 238, 232, 170 </TD><TD >palegreen = 152, 251, 152 </TD><TD >paleturquoise = 175, 238, 238 </TD></TR>
+<TR><TD >palevioletred = 219, 112, 147 </TD><TD >papayawhip = 255, 239, 213 </TD><TD >peachpuff = 255, 239, 213 </TD><TD >peru = 205, 133, 63 </TD><TD >pink = 255, 192, 203 </TD></TR>
+<TR><TD >plum = 221, 160, 221 </TD><TD >powderblue = 176, 224, 230 </TD><TD >purple = 128, 0, 128 </TD><TD >red = 255, 0, 0 </TD><TD >rosybrown = 188, 143, 143 </TD></TR>
+<TR><TD >royalblue = 65, 105, 225 </TD><TD >saddlebrown = 139, 69, 19 </TD><TD >salmon = 250, 128, 114 </TD><TD >sandybrown = 244, 164, 96 </TD><TD >seagreen = 46, 139, 87 </TD></TR>
+<TR><TD >seashell = 255, 245, 238 </TD><TD >sienna = 160, 82, 45 </TD><TD >silver = 192, 192, 192 </TD><TD >skyblue = 135, 206, 235 </TD><TD >slateblue = 106, 90, 205 </TD></TR>
+<TR><TD >slategray = 112, 128, 144 </TD><TD >snow = 255, 250, 250 </TD><TD >springgreen = 0, 255, 127 </TD><TD >steelblue = 70, 130, 180 </TD><TD >tan = 210, 180, 140 </TD></TR>
+<TR><TD >teal = 0, 128, 128 </TD><TD >thistle = 216, 191, 216 </TD><TD >tomato = 253, 99, 71 </TD><TD >turquoise = 64, 224, 208 </TD><TD >violet = 238, 130, 238 </TD></TR>
+<TR><TD >wheat = 245, 222, 179 </TD><TD >white = 255, 255, 255 </TD><TD >whitesmoke = 245, 245, 245 </TD><TD >yellow = 255, 255, 0 </TD><TD >yellowgreen = 154, 205, 50
+</TD></TR></TABLE></DIV>
+
</HTML>
diff --git a/doc/dump_modify.txt b/doc/dump_modify.txt
index 0f2613b77..081a252ec 100644
--- a/doc/dump_modify.txt
+++ b/doc/dump_modify.txt
@@ -1,241 +1,670 @@
"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
dump_modify command :h3
[Syntax:]
dump_modify dump-ID keyword values ... :pre
dump-ID = ID of dump to modify :ulb,l
one or more keyword/value pairs may be appended :l
-keyword = {append} or {every} or {flush} or {format} or {image} or {label} or {precision} or {region} or {scale} or {sort} or {thresh} or {unwrap} :l
+keyword = {acolor} or {adiam} or {amap} or {append} or {bcolor} or {bdiam} or {bgcolor} or {boxcolor} or {color} or {every} or {flush} or {format} or {image} or {label} or {precision} or {region} or {scale} or {sort} or {thresh} or {unwrap} :l
+ {acolor} args = type color
+ type = atom type or range of types (see below)
+ color = name of color or color1/color2/...
+ {adiam} args = type diam
+ type = atom type or range of types (see below)
+ diam = diameter of atoms of that type (distance units)
+ {amap} args = lo hi style N delta entry1 entry2 ... entryN
+ lo = number or {min} = lower bound of range of color map
+ hi = number or {max} = upper bound of range of color map
+ style = 2 letters = "b" or "c" or "s" plus "a" or "f"
+ "c" for continuous
+ "d" for discrete
+ "s" for sequential
+ "a" for absolute
+ "f" for fractional
+ delta = binsize (only used for style "s" = sequential)
+ binsize = range is divided into bins of this width
+ N = # of subsequent entries
+ entry = value color (for continuous style)
+ value = number or {min} or {max} = single value within range
+ color = name of color used for that value
+ entry = lo hi color (for discrete style)
+ lo/hi = number or {min} or {max} = lower/upper bound of subset of range
+ color = name of color used for that value
+ entry = color (for sequential style)
+ color = name of color used for a bin within range
{append} arg = {yes} or {no}
+ {bcolor} args = type color
+ type = bond type or range of types (see below)
+ color = name of color or color1/color2/...
+ {bdiam} args = type diam
+ type = bond type or range of types (see below)
+ diam = diameter of bonds of that type (distance units)
+ {bgcolor} arg = color
+ color = name of color for background
+ {boxcolor} arg = color
+ color = name of color for box lines
+ {color} args = name R G B
+ name = name of color
+ R,G,B = red/green/blue numeric values from 0.0 to 1.0
{element} args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
{every} arg = N
N = dump every this many timesteps
N can be a variable (see below)
{first} arg = {yes} or {no}
{format} arg = C-style format string for one line of output
{flush} arg = {yes} or {no}
{image} arg = {yes} or {no}
{label} arg = string
string = character string (e.g. BONDS) to use in header of dump local file
{pad} arg = Nchar = # of characters to convert timestep to
{precision} arg = power-of-10 value from 10 to 1000000
{region} arg = region-ID or "none"
{scale} arg = {yes} or {no}
{sort} arg = {off} or {id} or N or -N
off = no sorting of per-atom lines within a snapshot
id = sort per-atom lines by atom ID
N = sort per-atom lines in ascending order by the Nth column
-N = sort per-atom lines in descending order by the Nth column
{thresh} args = attribute operation value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operation = "<" or "<=" or ">" or ">=" or "==" or "!="
value = numeric value to compare to
these 3 args can be replaced by the word "none" to turn off thresholding
{unwrap} arg = {yes} or {no} :pre
:ule
[Examples:]
dump_modify 1 format "%d %d %20.15g %g %g" scale yes
dump_modify myDump image yes scale no flush yes
dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2
dump_modify xtcdump precision 10000
dump_modify 1 every 1000
dump_modify 1 every v_myVar :pre
+NOTE: add some image examples
+
[Description:]
Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.
+:line
+
+The {acolor} keyword applies only to the dump {image} style. It can
+be used with the "dump image"_dump_image.html command, with its {atom}
+keyword, when its color setting is {type}, to set the color that atoms
+of each type will be drawn in the image.
+
+The specified {type} should be an integer from 1 to Ntypes = the
+number of atom types. A wildcard asterisk can be used in place of or
+in conjunction with the {type} argument to specify a range of atom
+types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
+number of atom types, then an asterisk with no numeric values means
+all types from 1 to N. A leading asterisk means all types from 1 to n
+(inclusive). A trailing asterisk means all types from n to N
+(inclusive). A middle asterisk means all types from m to n
+(inclusive).
+
+The specified {color} can be a single color which is any of the 140
+pre-defined colors (see below) or a colorname defined by the
+dump_modify color option. Or it can be two or more colors separated
+by a "/" character, e.g. red/green/blue. In the former case, that
+color is assigned to all the specified atom types. In the latter
+case, the list of colors are assigned in a round-robin fashion
+to each of the specified atom types.
+
+:line
+
+The {adiam} keyword applies only to the dump {image} style. It can be
+used with the "dump image"_dump_image.html command, with its {atom}
+keyword, when its diam setting is {type}, to set the size that atoms
+of each type will be drawn in the image. The specified {type} should
+be an integer from 1 to Ntypes. As with the {acolor} keyword, a
+wildcard asterisk can be used as part of the {type} argument to
+specify a range of atomt types. The specified {diam} is the size in
+whatever distance "units"_units.html you are using, e.g. Angstroms.
+
+:line
+
+The {amap} keyword applies only to the dump {image} style. It can be
+used with the "dump image"_dump_image.html command, with its {atom}
+keyword, when its atom setting is an atom-attribute, to setup a color
+map. The color map is used to assign a specific RGB (red/green/blue)
+color value to an individual atom when it is drawn, based on the
+atom's attribute, which is a numeric value, e.g. its x-component of
+velocity if the atom-attribute "vx" was specified.
+
+The basic idea of a color map is that the atom-attribute will be
+within a range of values, and that range is associated with a a series
+of colors (e.g. red, blue, green). An atom's specific value (vx =
+-3.2) can then mapped to the series of colors (e.g. halfway between
+red and blue), and a specific color is determined via an interpolation
+procedure. There are other options for the mapping mechanism, all of
+which are explained on the "dump_modify"_dump_modify.html doc page.
+
+There are many possible options for the color map, enabled by the
+{amap} keyword. Here are the details.
+
+The {lo} and {hi} settings determine the range of values allowed for
+the atom attribute. If numeric values are used for {lo} and/or {hi},
+then values that are lower/higher than that value are set to the
+value. I.e. the range is static. If {lo} is specified as {min} or
+{hi} as {max} then the range is dynamic, and will the lower and/or
+upper bound will be calculated each time an image is drawn.
+
+The {style} setting is two letters, such as "ca". The first letter is
+either "c" for continuous, "d" for discrete, or "s" for sequential.
+The second letter is either "a" for absolute, or "f" for fractional.
+
+A continuous color map is one in which the color changes continuously
+from value to value within the range. A discrete color map is one in
+which discrete colors are assigned to sub-ranges of values within the
+range. A sequential color map is one in which discrete colors are
+assigned to a sequence of sub-ranges of values covering the entire
+range.
+
+An absolute color map is one in which the values to which colors are
+assigned are specified explicitly as values within the range. A
+fractional color map is one in which the values to which colors are
+assigned are specified as a fractional portion of the range. For
+example if the range is from -10.0 to 10.0, and the color red is to be
+assigned to atoms with a value of 5.0, then for an absolute color map
+the number 5.0 would be used. But for a fractional map, the number
+0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
+
+The {delta} setting is only specified if the style is sequential. It
+specifies the bin size to use within the range for assigning
+consecutive colors to. For example, if the range is from -10.0 to
+10.0 and a {delta} of 1.0 is used, then 20 colors will be assigned to
+the range. The first will be from -10.0 <= color1 < -9.0, then 2nd
+from -9.0 <= color2 < -8.0, etc.
+
+The {N} setting is how many entries follow. The format of the entries
+depends on whether the color map style is continuous, discrete or
+sequential. In all cases the {color} setting can be any of the 140
+pre-defined colors (see below) or a colorname defined by the
+dump_modify color option.
+
+For continuous color maps, each entry has a {value} and a {color}.
+The {value} is either a number within the range of values or {min} or
+{max}. The {value} of the first entry must be {min} and the {value}
+of hte last entry must be {max}. Any entries in between must have
+increasing values. Note that numeric values can be specified either
+as absolute numbers or as fractions (0.0 to 1.0) of the range,
+depending on the "a" or "f" in the style setting for the color map.
+
+Here is how the entries are used to determine the color of an
+individual atom, given the value X of its atom attribute. X will fall
+between 2 of the entry values. The color of the atom is linearly
+interpolated (in each of the RGB values) between the 2 colors
+associated with those entries. For example, if X = -5.0 and the 2
+surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
+atom's color will be halfway between "red" and "blue", which happens
+to be "purple".
+
+For discrete color maps, each entry has a {lo} and {hi} value and a
+{color}. The {lo} and {hi} settings are either numbers within the
+range of values or {lo} can be {min} or {hi} can be {max}. The {lo}
+and {hi} settings of the last entry must be {min} and {max}. Other
+entries can have any {lo} and {hi} values, including sub-ranges of
+values that overlap. Note that numeric {lo} and {hi} values can be
+specified either as absolute numbers or as fractions (0.0 to 1.0) of
+the range, depending on the "a" or "f" in the style setting for the
+color map.
+
+Here is how the entries are used to determine the color of an
+individual atom, given the value X of its atom attribute. The entries
+are scanned from first to last. The first time that {lo} <= X <=
+{hi}, X is assigned the color associated with that entry. You can
+think of the last entry as assigning a default color (since it will
+always be matched by X), and the earlier entries as colors that
+override the default. Also note that no interpolation of a color RGB
+is done. All atoms will be drawn with one of the colors in the list
+of entries.
+
+For sequential color maps, each entry has only a {color}. Here is how
+the entries are used to determine the color of an individual atom,
+given the value X of its atom attribute. The range is partitioned
+into N bins of width {binsize}. Thus X will fall in a specific bin
+from 1 to N, say the Mth bin. If it falls on a boundary between 2
+bins, it is considered to be in the higher of the 2 bins. Each bin is
+assigned a color from the E entries. If E < N, then the colors are
+repeated. For example if 2 entries with colors red and green are
+specified, then the odd numbered bins will be red and the even bins
+green. The color of the atom is the color of its bin. Note that the
+sequential color map is really a shorthand way of defining a discrete
+color map without having to specify where all the bin boundaries are.
+
+:line
+
The {append} keyword applies to all dump styles except {cfg} and {xtc}
and {dcd}. It also applies only to text output files, not to binary
or gzipped files. If specified as {yes}, then dump snapshots are
appended to the end of an existing dump file. If specified as {no},
then a new dump file will be created which will overwrite an existing
file with the same name. This keyword can only take effect if the
dump_modify command is used after the "dump"_dump.html command, but
before the first command that causes dump snapshots to be output,
e.g. a "run"_run.html or "minimize"_minimize.html command. Once the
dump file has been opened, this keyword has no further effect.
-The {element} keyword applies only to the the dump {cfg} style. It
-associates element names (e.g. H, C, Fe) with LAMMPS atom types, so
-that the "AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A
-visualization package can render atoms with the appropriate size and
-color. An element name is specified for each atom type (1 to Ntype)
-in the simulation. The same element name can be given to multiple
-atom types.
+:line
+
+The {bcolor} keyword applies only to the dump {image} style. It can
+be used with the "dump image"_dump_image.html command, with its {bond}
+keyword, when its color setting is {type}, to set the color that bonds
+of each type will be drawn in the image.
+
+The specified {type} should be an integer from 1 to Nbondtypes = the
+number of bond types. A wildcard asterisk can be used in place of or
+in conjunction with the {type} argument to specify a range of bond
+types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
+number of bond types, then an asterisk with no numeric values means
+all types from 1 to N. A leading asterisk means all types from 1 to n
+(inclusive). A trailing asterisk means all types from n to N
+(inclusive). A middle asterisk means all types from m to n
+(inclusive).
+
+The specified {color} can be a single color which is any of the 140
+pre-defined colors (see below) or a colorname defined by the
+dump_modify color option. Or it can be two or more colors separated
+by a "/" character, e.g. red/green/blue. In the former case, that
+color is assigned to all the specified bond types. In the latter
+case, the list of colors are assigned in a round-robin fashion to each
+of the specified bond types.
+
+:line
+
+The {bdiam} keyword applies only to the dump {image} style. It can be
+used with the "dump image"_dump_image.html command, with its {bond}
+keyword, when its diam setting is {type}, to set the diameter that
+bonds of each type will be drawn in the image. The specified {type}
+should be an integer from 1 to Nbondtypes. As with the {bcolor}
+keyword, a wildcard asterisk can be used as part of the {type}
+argument to specify a range of bond types. The specified {diam} is
+the size in whatever distance "units"_units.html you are using,
+e.g. Angstroms.
+
+:line
+
+The {bgcolor} keyword applies only to the dump {image} style. It sets
+the background color of each image. The color name can be any of the
+140 pre-defined colors (see below) or a colorname defined by the
+dump_modify color option.
+
+:line
+
+The {boxcolor} keyword applies only to the dump {image} style. It
+sets the color of the simulation box drawn around the atoms in each
+image. See the "dump image box" command for how to specify that a box
+be drawn. The color name can be any of the 140 pre-defined colors
+(see below) or a colorname defined by the dump_modify color option.
+
+:line
+
+The {element} keyword applies only to the the dump {cfg} and {image}
+styles. It associates element names (e.g. H, C, Fe) with LAMMPS atom
+types. In the case of dump {cfg}, it allows the "AtomEye"_atomeye
+visualization package to read the dump file and render atoms with the
+appropriate size and color. In the case of dump {image}, the output
+images will follow the same "AtomEye"_atomeye convention. An element
+name is specified for each atom type (1 to Ntype) in the simulation.
+The same element name can be given to multiple atom types.
+
+:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A)
+
+:line
The {every} keyword changes the dump frequency originally specified by
the "dump"_dump.html command to a new value. The every keyword can be
specified in one of two ways. It can be a numeric value in which case
it must be > 0. Or it can be an "equal-style variable"_variable.html,
which should be specified as v_name, where name is the variable name.
In this case, the variable is evaluated at the beginning of a run to
determine the next timestep at which a dump snapshot will be written
out. On that timestep, the variable will be evaluated again to
determine the next timestep, etc. Thus the variable should return
timestep values. See the stagger() and logfreq() math functions for
"equal-style variables"_variable.html, as examples of useful functions
to use in this context. Other similar math functions could easily be
added as options for "equal-style variables"_variable.html. When
using the variable option with the {every} keyword, you also need to
use the {first} option if you want an initial snapshot written to the
dump file. The {every} keyword cannot be used with the dump {dcd}
style.
For example, the following commands will
write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
variable s equal logfreq(10,3,10)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes :pre
+:line
+
The {first} keyword determines whether a dump snapshot is written on
the very first timestep after the dump command is invoked. This will
always occur if the current timestep is a multiple of N, the frequency
specified in the "dump"_dump.html command, including timestep 0. But
if this is not the case, a dump snapshot will only be written if the
setting of this keyword is {yes}. If it is {no}, which is the
default, then it will not be written.
+:line
+
The {flush} keyword determines whether a flush operation is invoked
after a dump snapshot is written to the dump file. A flush insures
the output in that file is current (no buffering by the OS), even if
LAMMPS halts before the simulation completes. Flushes cannot be
performed with dump style {xtc}.
The text-based dump styles have a default C-style format string which
simply specifies %d for integers and %g for real values. The {format}
keyword can be used to override the default with a new C-style format
string. Do not include a trailing "\n" newline character in the
format string. This option has no effect on the {dcd} and {xtc} dump
styles since they write binary files. Note that for the {cfg} style,
the first two fields (atom id and type) are not actually written into
the CFG file, though you must include formats for them in the format
string.
+:line
+
The {image} keyword applies only to the dump {atom} style. If the
image value is {yes}, 3 flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
example, an x image flag of -2 with a normalized coord of 0.5 means
the atom is in the center of the box, but has passed thru the box
boundary 2 times and is really 2 box lengths to the left of its
current coordinate. Note that for dump style {custom} these various
values can be printed in the dump file by using the appropriate atom
attributes in the dump command itself.
+:line
+
The {label} keyword applies only to the dump {local} style. When
it writes local informatoin, such as bond or angle topology
to a dump file, it will use the specified {label} to format
the header. By default this includes 2 lines:
ITEM: NUMBER OF ENTRIES
ITEM: ENTRIES ... :pre
The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
+:line
+
The {pad} keyword only applies when the dump filename is specified
with a wildcard "*" character which becomes the timestep. If {pad} is
0, which is the default, the timestep is converted into a string of
unpadded length, e.g. 100 or 12000 or 2000000. When {pad} is
specified with {Nchar} > 0, the string is padded with leading zeroes
so they are all the same length = {Nchar}. For example, pad 7 would
yield 0000100, 0012000, 2000000. This can be useful so that
post-processing programs can easily read the files in ascending
timestep order.
+:line
+
The {precision} keyword only applies to the dump {xtc} style. A
specified value of N means that coordinates are stored to 1/N
nanometer accuracy, e.g. for N = 1000, the coordinates are written to
1/1000 nanometer accuracy.
-The {region} keyword only applies to the dump {custom} and {cfg}
-styles. If specified, only atoms in the region will be written to the
-dump file. Only one region can be applied as a filter (the last one
-specified). See the "region"_region.html command for more details.
-Note that a region can be defined as the "inside" or "outside" of a
-geometric shape, and it can be the "union" or "intersection" of a
-series of simpler regions.
+:line
+
+The {region} keyword only applies to the dump {custom} and {cfg} and
+{image} styles. If specified, only atoms in the region will be
+written to the dump file or included in the image. Only one region
+can be applied as a filter (the last one specified). See the
+"region"_region.html command for more details. Note that a region can
+be defined as the "inside" or "outside" of a geometric shape, and it
+can be the "union" or "intersection" of a series of simpler regions.
+
+:line
The {scale} keyword applies only to the dump {atom} style. A scale
value of {yes} means atom coords are written in normalized units from
0.0 to 1.0 in each box dimension. If the simluation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. A
value of {no} means they are written in absolute distance units
(e.g. Angstroms or sigma).
+:line
+
The {sort} keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of {off} means they will
typically be written in indeterminate order, either in serial or
parallel. This is the case even in serial if the "atom_modify
sort"_atom_modify.html option is turned on, which it is by default, to
improve performance. A sort value of {id} means sort the output by
atom ID. A sort value of N or -N means sort the output by the value
in the Nth column of per-atom info in either ascending or descending
order. The dump {local} style cannot be sorted by atom ID, since
there are typically multiple lines of output per atom. Some dump
styles, such as {dcd} and {xtc}, require sorting by atom ID to format
the output file correctly.
IMPORTANT NOTE: Unless it is required by the dump style, sorting dump
file output requires extra overhead in terms of CPU and communication
cost, as well as memory, versus unsorted output.
-The {thresh} keyword only applies to the dump {custom} and {cfg}
-styles. Multiple thresholds can be specified. Specifying "none"
-turns off all threshold criteria. If thresholds are specified, only
-atoms whose attributes meet all the threshold criteria are written to
-the dump file. The possible attributes that can be tested for are the
-same as those that can be specified in the "dump custom"_dump.html
-command. Note that different attributes can be output by the dump
-custom command than are used as threshold criteria by the dump_modify
-command. E.g. you can output the coordinates and stress of atoms
-whose energy is above some threshold.
+:line
+
+The {thresh} keyword only applies to the dump {custom} and {cfg} and
+{image} styles. Multiple thresholds can be specified. Specifying
+"none" turns off all threshold criteria. If thresholds are specified,
+only atoms whose attributes meet all the threshold criteria are
+written to the dump file or included in the image. The possible
+attributes that can be tested for are the same as those that can be
+specified in the "dump custom"_dump.html command. Note that different
+attributes can be output by the dump custom command than are used as
+threshold criteria by the dump_modify command. E.g. you can output
+the coordinates and stress of atoms whose energy is above some
+threshold.
+
+:line
The {unwrap} keyword only applies to the dump {dcd} and {xtc} styles.
If set to {yes}, coordinates will be written "unwrapped" by the image
flags for each atom. Unwrapped means that if the atom has passed thru
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that these coordinates may thus be far outside the
box size stored with the snapshot.
+:line
+
[Restrictions:] none
[Related commands:]
-"dump"_dump.html, "undump"_undump.html
+"dump"_dump.html, "dump image"_dump_image.html, "undump"_undump.html
[Default:]
The option defaults are
+acolor = * red/green/blue/yellow/aqua/cyan
+adiam = * 1.0
+amap = min max cf 2 0.0 blue 1.0 red
append = no
+bgcolor = black
+boxcolor = yellow
+color = 140 color names are pre-defined as listed below
element = "C" for every atom type
every = whatever it was set to via the "dump"_dump.html command
first = no
-flush = yes (except for the dump {xtc} style)
+flush = yes
format = %d and %g for each integer or floating point value
image = no
label = ENTRIES
pad = 0
precision = 1000
region = none
scale = yes
sort = off for dump styles {atom}, {custom}, {cfg}, and {local}
sort = id for dump styles {dcd}, {xtc}, and {xyz}
thresh = none
unwrap = no :ul
+
+:line
+
+These are the 140 colors that LAMMPS pre-defines for use with the
+"dump image"_dump_image.html and dump_modify commands. Additional
+colors can be defined with the dump_modify color command. The 3
+numbers listed for each name are the RGB (red/green/blue) values.
+Divide each value by 255 to get the equivalent 0.0 to 1.0 value.
+
+aliceblue = 240, 248, 255 |
+antiquewhite = 250, 235, 215 |
+aqua = 0, 255, 255 |
+aquamarine = 127, 255, 212 |
+azure = 240, 255, 255 |
+beige = 245, 245, 220 |
+bisque = 255, 228, 196 |
+black = 0, 0, 0 |
+blanchedalmond = 255, 255, 205 |
+blue = 0, 0, 255 |
+blueviolet = 138, 43, 226 |
+brown = 165, 42, 42 |
+burlywood = 222, 184, 135 |
+cadetblue = 95, 158, 160 |
+chartreuse = 127, 255, 0 |
+chocolate = 210, 105, 30 |
+coral = 255, 127, 80 |
+cornflowerblue = 100, 149, 237 |
+cornsilk = 255, 248, 220 |
+crimson = 220, 20, 60 |
+cyan = 0, 255, 255 |
+darkblue = 0, 0, 139 |
+darkcyan = 0, 139, 139 |
+darkgoldenrod = 184, 134, 11 |
+darkgray = 169, 169, 169 |
+darkgreen = 0, 100, 0 |
+darkkhaki = 189, 183, 107 |
+darkmagenta = 139, 0, 139 |
+darkolivegreen = 85, 107, 47 |
+darkorange = 255, 140, 0 |
+darkorchid = 153, 50, 204 |
+darkred = 139, 0, 0 |
+darksalmon = 233, 150, 122 |
+darkseagreen = 143, 188, 143 |
+darkslateblue = 72, 61, 139 |
+darkslategray = 47, 79, 79 |
+darkturquoise = 0, 206, 209 |
+darkviolet = 148, 0, 211 |
+deeppink = 255, 20, 147 |
+deepskyblue = 0, 191, 255 |
+dimgray = 105, 105, 105 |
+dodgerblue = 30, 144, 255 |
+firebrick = 178, 34, 34 |
+floralwhite = 255, 250, 240 |
+forestgreen = 34, 139, 34 |
+fuchsia = 255, 0, 255 |
+gainsboro = 220, 220, 220 |
+ghostwhite = 248, 248, 255 |
+gold = 255, 215, 0 |
+goldenrod = 218, 165, 32 |
+gray = 128, 128, 128 |
+green = 0, 128, 0 |
+greenyellow = 173, 255, 47 |
+honeydew = 240, 255, 240 |
+hotpink = 255, 105, 180 |
+indianred = 205, 92, 92 |
+indigo = 75, 0, 130 |
+ivory = 255, 240, 240 |
+khaki = 240, 230, 140 |
+lavender = 230, 230, 250 |
+lavenderblush = 255, 240, 245 |
+lawngreen = 124, 252, 0 |
+lemonchiffon = 255, 250, 205 |
+lightblue = 173, 216, 230 |
+lightcoral = 240, 128, 128 |
+lightcyan = 224, 255, 255 |
+lightgoldenrodyellow = 250, 250, 210 |
+lightgreen = 144, 238, 144 |
+lightgrey = 211, 211, 211 |
+lightpink = 255, 182, 193 |
+lightsalmon = 255, 160, 122 |
+lightseagreen = 32, 178, 170 |
+lightskyblue = 135, 206, 250 |
+lightslategray = 119, 136, 153 |
+lightsteelblue = 176, 196, 222 |
+lightyellow = 255, 255, 224 |
+lime = 0, 255, 0 |
+limegreen = 50, 205, 50 |
+linen = 250, 240, 230 |
+magenta = 255, 0, 255 |
+maroon = 128, 0, 0 |
+mediumaquamarine = 102, 205, 170 |
+mediumblue = 0, 0, 205 |
+mediumorchid = 186, 85, 211 |
+mediumpurple = 147, 112, 219 |
+mediumseagreen = 60, 179, 113 |
+mediumslateblue = 123, 104, 238 |
+mediumspringgreen = 0, 250, 154 |
+mediumturquoise = 72, 209, 204 |
+mediumvioletred = 199, 21, 133 |
+midnightblue = 25, 25, 112 |
+mintcream = 245, 255, 250 |
+mistyrose = 255, 228, 225 |
+moccasin = 255, 228, 181 |
+navajowhite = 255, 222, 173 |
+navy = 0, 0, 128 |
+oldlace = 253, 245, 230 |
+olive = 128, 128, 0 |
+olivedrab = 107, 142, 35 |
+orange = 255, 165, 0 |
+orangered = 255, 69, 0 |
+orchid = 218, 112, 214 |
+palegoldenrod = 238, 232, 170 |
+palegreen = 152, 251, 152 |
+paleturquoise = 175, 238, 238 |
+palevioletred = 219, 112, 147 |
+papayawhip = 255, 239, 213 |
+peachpuff = 255, 239, 213 |
+peru = 205, 133, 63 |
+pink = 255, 192, 203 |
+plum = 221, 160, 221 |
+powderblue = 176, 224, 230 |
+purple = 128, 0, 128 |
+red = 255, 0, 0 |
+rosybrown = 188, 143, 143 |
+royalblue = 65, 105, 225 |
+saddlebrown = 139, 69, 19 |
+salmon = 250, 128, 114 |
+sandybrown = 244, 164, 96 |
+seagreen = 46, 139, 87 |
+seashell = 255, 245, 238 |
+sienna = 160, 82, 45 |
+silver = 192, 192, 192 |
+skyblue = 135, 206, 235 |
+slateblue = 106, 90, 205 |
+slategray = 112, 128, 144 |
+snow = 255, 250, 250 |
+springgreen = 0, 255, 127 |
+steelblue = 70, 130, 180 |
+tan = 210, 180, 140 |
+teal = 0, 128, 128 |
+thistle = 216, 191, 216 |
+tomato = 253, 99, 71 |
+turquoise = 64, 224, 208 |
+violet = 238, 130, 238 |
+wheat = 245, 222, 179 |
+white = 255, 255, 255 |
+whitesmoke = 245, 245, 245 |
+yellow = 255, 255, 0 |
+yellowgreen = 154, 205, 50 :tb(c=5,s=|)
diff --git a/doc/fix_srd.html b/doc/fix_srd.html
index 803d3c59e..b9c5aa5dd 100644
--- a/doc/fix_srd.html
+++ b/doc/fix_srd.html
@@ -1,375 +1,377 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>fix srd command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID group-ID srd N groupbig-ID Tsrd hgrid seed keyword value ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
<LI>srd = style name of this fix command
<LI>N = reset SRD particle velocities every this many timesteps
<LI>groupbig-ID = ID of group of large particles that SRDs interact with
<LI>Tsrd = temperature of SRD particles (temperature units)
<LI>hgrid = grid spacing for SRD grouping (distance units)
<LI>seed = random # seed (positive integer)
</UL>
<UL><LI>zero or more keyword/value pairs may be appended
<LI>keyword = <I>lamda</I> or <I>collision</I> or <I>overlap</I> or <I>inside</I> or <I>exact</I> or <I>radius</I> or <I>bounce</I> or <I>search</I> or <I>cubic</I> or <I>shift</I> or <I>stream</I>
<PRE> <I>lamda</I> value = mean free path of SRD particles (distance units)
<I>collision</I> value = <I>noslip</I> or <I>slip</I> = collision model
<I>overlap</I> value = <I>yes</I> or <I>no</I> = whether big particles may overlap
<I>inside</I> value = <I>error</I> or <I>warn</I> or <I>ignore</I> = how SRD particles which end up inside a big particle are treated
<I>exact</I> value = <I>yes</I> or <I>no</I>
<I>radius</I> value = rfactor = scale collision radius by this factor
<I>bounce</I> value = Nbounce = max # of collisions an SRD particle can undergo in one timestep
<I>search</I> value = sgrid = grid spacing for collision partner searching (distance units)
<I>cubic</I> values = style tolerance
style = <I>error</I> or <I>warn</I>
tolerance = fractional difference allowed (0 <= tol <= 1)
<I>shift</I> values = style seed
style = <I>no</I> or <I>yes</I> or <I>possible</I>
seed = random # seed (positive integer)
<I>stream</I> value = <I>yes</I> or <I>no</I> = whether or not streaming velocity is added for shear deformation
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>fix 1 srd srd 10 big 1.0 0.25 482984
fix 1 srd srd 10 big 0.5 0.25 482984 collision slip search 0.5
</PRE>
<P><B>Description:</B>
</P>
<P>Treat a group of partilces as stochastic rotation dynamics (SRD)
particles that serve as a background solvent when interacting with big
(colloidal) particles in groupbig-ID. The SRD formalism is described
in <A HREF = "#Hecht">(Hecht)</A>. The key idea behind using SRD particles as a
cheap coarse-grained solvent is that SRD particles do not interact
with each other, but only with the solute particles, which in LAMMPS
can be spheroids, ellipsoids, or rigid bodies containing multiples
spherioids and ellipsoids. The collision and rotation properties of
the model imbue the SRD particles with fluid-like properties,
including an effective viscosity. Thus simulations with large solute
particles can be run more quickly, to measure solute propoerties like
diffusivity and viscosity in a background fluid. The usual LAMMPS
fixes for such simulations, such as <A HREF = "fix_deform.html">fix deform</A>, <A HREF = "fix_viscosity.html">fix
viscosity</A>, and <A HREF = "fix_nvt_sllod.html">fix nvt/sllod</A>,
can be used in conjunction with the SRD model.
</P>
<P>For more details on how the SRD model is implemented in LAMMPS, <A HREF = "#Petersen">this
paper</A> describes the implementation and usage of pure SRD
fluids. <A HREF = "#Lechman">This paper</A>, which is nearly complete, describes
the implementation and usage of mixture systems (solute particles in
an SRD fluid). See the examples/srd directory for sample input
scripts using SRD particles in both settings.
</P>
<P>This fix does 2 things:
</P>
<P>(1) It advects the SRD particles, performing collisions between SRD
and big particles or walls every timestep, imparting force and torque
to the big particles. Collisions also change the position and
velocity of SRD particles.
</P>
<P>(2) It resets the velocity distribution of SRD particles via random
rotations every N timesteps.
</P>
<P>SRD particles have a mass, temperature, characteristic timestep
dt_SRD, and mean free path between collisions (lamda). The
fundamental equation relating these 4 quantities is
</P>
<PRE>lamda = dt_SRD * sqrt(Kboltz * Tsrd / mass)
</PRE>
<P>The mass of SRD particles is set by the <A HREF = "mass.html">mass</A> command
elsewhere in the input script. The SRD timestep dt_SRD is N times the
step dt defined by the <A HREF = "timestep.html">timestep</A> command. Big
particles move in the normal way via a time integration <A HREF = "fix.html">fix</A>
with a short timestep dt. SRD particles advect with a large timestep
dt_SRD >= dt.
</P>
<P>If the <I>lamda</I> keyword is not specified, the the SRD temperature
<I>Tsrd</I> is used in the above formula to compute lamda. If the <I>lamda</I>
keyword is specified, then the <I>Tsrd</I> setting is ignored and the above
equation is used to compute the SRD temperature.
</P>
<P>The characteristic length scale for the SRD fluid is set by <I>hgrid</I>
which is used to bin SRD particles for purposes of resetting their
velocities. Normally hgrid is set to be 1/4 of the big particle
diameter or smaller, to adequately resolve fluid properties around the
big particles.
</P>
<P>Lamda cannot be smaller than 0.6 * hgrid, else an error is generated.
The velocities of SRD particles are bounded by Vmax, which is set so
that an SRD particle will not advect further than Dmax = 4*lamda in
dt_SRD. This means that roughly speaking, Dmax should not be larger
than a big particle diameter, else SRDs may pass thru big particles
without colliding. A warning is generated if this is the case.
</P>
<P>Collisions between SRD particles and big particles or walls are
modeled as a lightweight SRD point particle hitting a heavy big
particle of given diameter or a wall at a point on its surface and
bouncing off with a new velocity. The collision changes the momentum
of the SRD particle. It imparts a force and torque to the big
particle. It imparts a force to a wall. Static or moving SRD walls
are setup via the <A HREF = "fix_wall_srd.html">fix wall/srd</A> command. For the
remainder of this doc page, a collision of an SRD particle with a wall
can be viewed as a collision with a big particle of infinite radius
and mass.
</P>
<P>The <I>collision</I> keyword sets the style of collisions. The <I>slip</I>
style means that the tangential component of the SRD particle momentum
is preserved. Thus a force is imparted to a big particle, but no
torque. The normal component of the new SRD velocity is sampled from
a Gaussian distribution at temperature <I>Tsrd</I>.
</P>
<P>For the <I>noslip</I> style, both the normal and tangential components of
the new SRD velocity are sampled from a Gaussian distribution at
temperature <I>Tsrd</I>. Additionally, a new tangential direction for the
SRD velocity is chosen randomly. This collision style imparts torque
to a big particle. Thus a time integrator <A HREF = "fix.html">fix</A> that rotates
the big particles appropriately should be used.
</P>
<HR>
<P>The <I>overlap</I> keyword should be set to <I>yes</I> if two (or more) big
particles can ever overlap. This depends on the pair potential
interaction used for big-big interactions, or could be the case if
multiple big particles are held together as rigid bodies via the <A HREF = "fix_rigid.html">fix
rigid</A> command. If the <I>overlap</I> keyword is <I>no</I> and
big particles do in fact overlap, then SRD/big collisions can generate
an error if an SRD ends up inside two (or more) big particles at once.
How this error is treated is determined by the <I>inside</I> keyword.
Running with <I>overlap</I> set to <I>no</I> allows for faster collision
checking, so it should only be set to <I>yes</I> if needed.
</P>
<P>The <I>inside</I> keyword determines how a collision is treated if the
computation determines that the timestep started with the SRD particle
already inside a big particle. If the setting is <I>error</I> then this
generates an error message and LAMMPS stops. If the setting is <I>warn</I>
then this generates a warning message and the code continues. If the
setting is <I>ignore</I> then no message is generated. One of the output
quantities logged by the fix (see below) tallies the number of such
events, so it can be monitored. Note that once an SRD particle is
inside a big particle, it may remain there for several steps until it
drifts outside the big particle.
</P>
<P>The <I>exact</I> keyword determines how accurately collisions are computed.
A setting of <I>yes</I> computes the time and position of each collision as
SRD and big particles move together. A setting of <I>no</I> estimates the
position of each collision based on the end-of-timestep positions of
the SRD and big particle. If <I>overlap</I> is set to yes, the setting of
the <I>exact</I> keyword is ignored since time-accurate collisions are
needed.
</P>
<P>The <I>radius</I> keyword scales the effective size of big particles. If
big particles will overlap as they undergo dynamics, then this keyword
can be used to scale down their effective collision radius by an
amount <I>rfactor</I>, so that SRD particle will only collide with one big
particle at a time. For example, in a Lennard-Jones system at a
temperature of 1.0 (in reduced LJ units), the minimum separation
bewteen two big particles is as small as about 0.88 sigma. Thus an
<I>rfactor</I> value of 0.85 should prevent dual collisions.
</P>
<P>The <I>bounce</I> keyword can be used to limit the maximum number of
collisions an SRD particle undergoes in a single timestep as it
bounces between nearby big particles. Note that if the limit is
reached, the SRD can be left inside a big particle. A setting of 0 is
the same as no limit.
</P>
<HR>
<P>There are 2 kinds of bins created and maintained when running an SRD
simulation. The first are "SRD bins" which are used to bin SRD
particles and reset their velocities, as discussed above. The second
are "search bins" which are used to identify SRD/big particle
collisions.
</P>
<P>The <I>search</I> keyword can be used to choose a search bin size for
identifying SRD/big particle collisions. The default is to use the
<I>hgrid</I> parameter for SRD bins as the search bin size. Choosing a
smaller or large value may be more efficient, depending on the
problem. But, in a statistical sense, it should not change the
simulation results.
</P>
<P>The <I>cubic</I> keyword can be used to generate an error or warning when
the bin size chosen by LAMMPS creates SRD bins that are non-cubic or
different than the requested value of <I>hgrid</I> by a specified
<I>tolerance</I>. Note that using non-cubic SRD bins can lead to
undetermined behavior when rotating the velocities of SRD particles,
hence LAMMPS tries to protect you from this problem.
</P>
<P>LAMMPS attempts to set the SRD bin size to exactly <I>hgrid</I>. However,
there must be an integer number of bins in each dimension of the
simulation box. Thus the actual bin size will depend on the size and
shape of the overall simulation box. The actual bin size is printed
as part of the SRD output when a simulation begins.
</P>
<P>If the actual bin size in non-cubic by an amount exceeding the
tolerance, an error or warning is printed, depending on the style of
the <I>cubic</I> keyword. Likewise, if the actual bin size differs from
the requested <I>hgrid</I> value by an amount exceeding the tolerance, then
an error or warning is printed. The <I>tolerance</I> is a fractional
difference. E.g. a tolerance setting of 0.01 on the shape means that
if the ratio of any 2 bin dimensions exceeds (1 +/- tolerance) then an
error or warning is generated. Similarly, if the ratio of any bin
dimension with <I>hgrid</I> exceeds (1 +/- tolerance), then an error or
warning is generated.
</P>
<P>IMPORTANT NOTE: The fix srd command can be used with simluations the
size and/or shape of the simulation box changes. This can be due to
non-periodic boundary conditions or the use of fixes such as the <A HREF = "fix_deform.html">fix
deform</A> or <A HREF = "fix_wall_srd.html">fix wall/srd</A> commands
to impose a shear on an SRD fluid or an interaction with an external
wall. If the box size changes then the size of SRD bins must be
recalculated every reneighboring. This is not necessary if only the
box shape changes. This re-binning is always done so as to fit an
integer number of bins in the current box dimension, whether it be a
fixed, shrink-wrapped, or periodic boundary, as set by the
<A HREF = "boundary.html">boundary</A> command. If the box size or shape changes,
then the size of the search bins must be recalculated avery
reneighboring. Note that changing the SRD bin size may alter the
properties of the SRD fluid, such as its viscosity.
</P>
<P>The <I>shift</I> keyword determines whether the coordinates of SRD
particles are randomly shifted when binned for purposes of rotating
their velocities. When no shifting is performed, SRD particles are
binned and the velocity distribution of the set of SRD particles in
each bin is adjusted via a rotation operator. This is a statistically
valid operation if SRD particles move sufficiently far between
successive rotations. This is determined by their mean-free path
lamda. If lamda is less than 0.6 of the SRD bin size, then shifting
is required. A shift means that all of the SRD particles are shifted
by a vector whose coordinates are chosen randomly in the range [-1/2
bin size, 1/2 bin size]. Note that all particles are shifted by the
same vector. The specified random number seed is used to generate
these vectors. This operation sufficiently randomizes which SRD
particles are in the same bin, even if lamda is small.
</P>
<P>If the <I>shift</I> style is set to <I>no</I>, then no shifting is performed,
but bin data will be communicated if bins overlap processor
boundaries. An error will be generated if lamda < 0.6 of the SRD bin
size. If the <I>shift</I> style is set to <I>possible</I>, then shifting is
performed only if lamda < 0.6 of the SRD bin size. A warning is
generated to let you know this is occurring. If the <I>shift</I> style is
set to <I>yes</I> then shifting is performed regardless of the magnitude of
lamda.
</P>
<P>The shift seed is not used if the <I>shift</I> style is set to <I>no</I>, but
must still be specified.
</P>
<P>Note that shifting of SRD coordinates requires extra communication,
hence it should not normally be enabled unless required.
</P>
<P>The <I>stream</I> keyword should be used when SRD particles are used with
the <A HREF = "fix_deform.html">fix deform</A> command to perform a simulation
undergoing shear, e.g. to measure a viscosity. If the <I>stream</I> style
is set to <I>yes</I>, then the mean velocity of each bin of SRD particles
is set to the streaming velocity of the deforming box, each time SRD
velocities are reset, every N timesteps. If the <I>stream</I> style is set
to <I>no</I>, then the mean velocity is unchanged, which may mean that it
takes a long time for the SRD fluid to come to equilibrium with a
velocity profile that matches the simulation box deformation.
</P>
<HR>
<P>IMPORTANT NOTE: This fix is normally used for simulations with a huge
number of SRD particles relative to the number of big particles,
e.g. 100 to 1. In this scenario, computations that involve only big
particles (neighbor list creation, communication, time integration)
can slow down dramatically due to the large number of background SRD
particles.
</P>
<P>Three other input script commands will largely overcome this effect,
speeding up an SRD simulation by a significant amount. These are the
<A HREF = "atom_modify.html">atom_modify first</A>, <A HREF = "neigh_modify.html">neigh_modify
include</A>, and <A HREF = "communicate.html">communicate group</A>
commands. Each takes a group-ID as an argument, which in this case
should be the group-ID of the big solute particles.
</P>
<P>Additionally, when a <A HREF = "pair_style.html">pair_style</A> for big/big particle
interactions is specified, the <A HREF = "pair_coeff.html">pair_coeff</A> command
should be used to turn off big/SRD interactions, e.g. by setting their
epsilon or cutoff length to 0.0.
</P>
<P>The "delete_atoms overlap" command may be useful in setting up an SRD
simulation to insure there are no initial overlaps between big and SRD
particles.
</P>
<HR>
<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
</P>
<P>No information about this fix is written to <A HREF = "restart.html">binary restart
files</A>. None of the <A HREF = "fix_modify.html">fix_modify</A> options
are relevant to this fix.
</P>
<P>This fix tabulates several SRD statistics which are stored in a vector
of length 12, which can be accessed by various <A HREF = "Section_howto.html#4_15">output
commands</A>. The vector values calculated by
this fix are "intensive", meaning they do not scale with the size of
the simulation. Technically, the first 8 do scale with the size of
the simulation, but treating them as intensive means they are not
scaled when printed as part of thermodyanmic output.
</P>
<P>These are the 12 quantities. All are values for the current timestep,
except the last three which are cummulative quantities since the
beginning of the run.
</P>
<UL><LI>(1) # of SRD/big collision checks performed
<LI>(2) # of SRDs which had a collision
<LI>(3) # of SRD/big colllisions (including multiple bounces)
<LI>(4) # of SRD particles inside a big particle
<LI>(5) # of SRD particles whose velocity was rescaled to be < Vmax
<LI>(6) # of bins for collision searching
<LI>(7) # of bins for SRD velocity rotation
<LI>(8) # of bins in which SRD temperature was computed
<LI>(9) SRD temperature
<LI>(10) # of SRD particles which have undergone max # of bounces
<LI>(11) max # of bounces any SRD particle has had in a single step
<LI>(12) # of reneighborings dues to SRD particles moving too far
</UL>
<P>No parameter of this fix can be used with the <I>start/stop</I> keywords of
the <A HREF = "run.html">run</A> command. This fix is not invoked during <A HREF = "minimize.html">energy
minimization</A>.
</P>
-<P><B>Restrictions:</B> none
+<P><B>Restrictions:</B>
</P>
<P>This command can only be used if LAMMPS was built with the "srd"
package. See the <A HREF = "Section_start.html#2_3">Making LAMMPS</A> section for
more info on packages.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "fix_wall_srd.html">fix wall/srd</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are lamda inferred from Tsrd, collision = noslip,
overlap = no, inside = error, exact = yes, radius = 1.0, bounce = 0,
search = hgrid, cubic = error 0.01, shift = no, stream = yes.
</P>
<HR>
<A NAME = "Hecht"></A>
<P><B>(Hecht)</B> Hecht, Harting, Ihle, Herrmann, Phys Rev E, 72, 011408 (2005).
</P>
<A NAME = "Petersen"></A>
<P><B>(Petersen)</B> Petersen, Lechman, Plimpton, Grest, in' t Veld, Schunk, J
Chem Phys, 132, 174106 (2010).
</P>
-<P>:link(Lechman) <B>(Lechman)</B> Lechman, et al, in preparation (2010).
+<A NAME = "Lechman"></A>
+
+<P><B>(Lechman)</B> Lechman, et al, in preparation (2010).
</P>
</HTML>
diff --git a/doc/fix_srd.txt b/doc/fix_srd.txt
index 1819101db..7a206fa18 100644
--- a/doc/fix_srd.txt
+++ b/doc/fix_srd.txt
@@ -1,365 +1,366 @@
"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
fix srd command :h3
[Syntax:]
fix ID group-ID srd N groupbig-ID Tsrd hgrid seed keyword value ... :pre
ID, group-ID are documented in "fix"_fix.html command
srd = style name of this fix command
N = reset SRD particle velocities every this many timesteps
groupbig-ID = ID of group of large particles that SRDs interact with
Tsrd = temperature of SRD particles (temperature units)
hgrid = grid spacing for SRD grouping (distance units)
seed = random # seed (positive integer) :ul
zero or more keyword/value pairs may be appended :ulb,l
keyword = {lamda} or {collision} or {overlap} or {inside} or {exact} or {radius} or {bounce} or {search} or {cubic} or {shift} or {stream} :l
{lamda} value = mean free path of SRD particles (distance units)
{collision} value = {noslip} or {slip} = collision model
{overlap} value = {yes} or {no} = whether big particles may overlap
{inside} value = {error} or {warn} or {ignore} = how SRD particles which end up inside a big particle are treated
{exact} value = {yes} or {no}
{radius} value = rfactor = scale collision radius by this factor
{bounce} value = Nbounce = max # of collisions an SRD particle can undergo in one timestep
{search} value = sgrid = grid spacing for collision partner searching (distance units)
{cubic} values = style tolerance
style = {error} or {warn}
tolerance = fractional difference allowed (0 <= tol <= 1)
{shift} values = style seed
style = {no} or {yes} or {possible}
seed = random # seed (positive integer)
{stream} value = {yes} or {no} = whether or not streaming velocity is added for shear deformation :pre
:ule
[Examples:]
fix 1 srd srd 10 big 1.0 0.25 482984
fix 1 srd srd 10 big 0.5 0.25 482984 collision slip search 0.5 :pre
[Description:]
Treat a group of partilces as stochastic rotation dynamics (SRD)
particles that serve as a background solvent when interacting with big
(colloidal) particles in groupbig-ID. The SRD formalism is described
in "(Hecht)"_#Hecht. The key idea behind using SRD particles as a
cheap coarse-grained solvent is that SRD particles do not interact
with each other, but only with the solute particles, which in LAMMPS
can be spheroids, ellipsoids, or rigid bodies containing multiples
spherioids and ellipsoids. The collision and rotation properties of
the model imbue the SRD particles with fluid-like properties,
including an effective viscosity. Thus simulations with large solute
particles can be run more quickly, to measure solute propoerties like
diffusivity and viscosity in a background fluid. The usual LAMMPS
fixes for such simulations, such as "fix deform"_fix_deform.html, "fix
viscosity"_fix_viscosity.html, and "fix nvt/sllod"_fix_nvt_sllod.html,
can be used in conjunction with the SRD model.
For more details on how the SRD model is implemented in LAMMPS, "this
paper"_#Petersen describes the implementation and usage of pure SRD
fluids. "This paper"_#Lechman, which is nearly complete, describes
the implementation and usage of mixture systems (solute particles in
an SRD fluid). See the examples/srd directory for sample input
scripts using SRD particles in both settings.
This fix does 2 things:
(1) It advects the SRD particles, performing collisions between SRD
and big particles or walls every timestep, imparting force and torque
to the big particles. Collisions also change the position and
velocity of SRD particles.
(2) It resets the velocity distribution of SRD particles via random
rotations every N timesteps.
SRD particles have a mass, temperature, characteristic timestep
dt_SRD, and mean free path between collisions (lamda). The
fundamental equation relating these 4 quantities is
lamda = dt_SRD * sqrt(Kboltz * Tsrd / mass) :pre
The mass of SRD particles is set by the "mass"_mass.html command
elsewhere in the input script. The SRD timestep dt_SRD is N times the
step dt defined by the "timestep"_timestep.html command. Big
particles move in the normal way via a time integration "fix"_fix.html
with a short timestep dt. SRD particles advect with a large timestep
dt_SRD >= dt.
If the {lamda} keyword is not specified, the the SRD temperature
{Tsrd} is used in the above formula to compute lamda. If the {lamda}
keyword is specified, then the {Tsrd} setting is ignored and the above
equation is used to compute the SRD temperature.
The characteristic length scale for the SRD fluid is set by {hgrid}
which is used to bin SRD particles for purposes of resetting their
velocities. Normally hgrid is set to be 1/4 of the big particle
diameter or smaller, to adequately resolve fluid properties around the
big particles.
Lamda cannot be smaller than 0.6 * hgrid, else an error is generated.
The velocities of SRD particles are bounded by Vmax, which is set so
that an SRD particle will not advect further than Dmax = 4*lamda in
dt_SRD. This means that roughly speaking, Dmax should not be larger
than a big particle diameter, else SRDs may pass thru big particles
without colliding. A warning is generated if this is the case.
Collisions between SRD particles and big particles or walls are
modeled as a lightweight SRD point particle hitting a heavy big
particle of given diameter or a wall at a point on its surface and
bouncing off with a new velocity. The collision changes the momentum
of the SRD particle. It imparts a force and torque to the big
particle. It imparts a force to a wall. Static or moving SRD walls
are setup via the "fix wall/srd"_fix_wall_srd.html command. For the
remainder of this doc page, a collision of an SRD particle with a wall
can be viewed as a collision with a big particle of infinite radius
and mass.
The {collision} keyword sets the style of collisions. The {slip}
style means that the tangential component of the SRD particle momentum
is preserved. Thus a force is imparted to a big particle, but no
torque. The normal component of the new SRD velocity is sampled from
a Gaussian distribution at temperature {Tsrd}.
For the {noslip} style, both the normal and tangential components of
the new SRD velocity are sampled from a Gaussian distribution at
temperature {Tsrd}. Additionally, a new tangential direction for the
SRD velocity is chosen randomly. This collision style imparts torque
to a big particle. Thus a time integrator "fix"_fix.html that rotates
the big particles appropriately should be used.
:line
The {overlap} keyword should be set to {yes} if two (or more) big
particles can ever overlap. This depends on the pair potential
interaction used for big-big interactions, or could be the case if
multiple big particles are held together as rigid bodies via the "fix
rigid"_fix_rigid.html command. If the {overlap} keyword is {no} and
big particles do in fact overlap, then SRD/big collisions can generate
an error if an SRD ends up inside two (or more) big particles at once.
How this error is treated is determined by the {inside} keyword.
Running with {overlap} set to {no} allows for faster collision
checking, so it should only be set to {yes} if needed.
The {inside} keyword determines how a collision is treated if the
computation determines that the timestep started with the SRD particle
already inside a big particle. If the setting is {error} then this
generates an error message and LAMMPS stops. If the setting is {warn}
then this generates a warning message and the code continues. If the
setting is {ignore} then no message is generated. One of the output
quantities logged by the fix (see below) tallies the number of such
events, so it can be monitored. Note that once an SRD particle is
inside a big particle, it may remain there for several steps until it
drifts outside the big particle.
The {exact} keyword determines how accurately collisions are computed.
A setting of {yes} computes the time and position of each collision as
SRD and big particles move together. A setting of {no} estimates the
position of each collision based on the end-of-timestep positions of
the SRD and big particle. If {overlap} is set to yes, the setting of
the {exact} keyword is ignored since time-accurate collisions are
needed.
The {radius} keyword scales the effective size of big particles. If
big particles will overlap as they undergo dynamics, then this keyword
can be used to scale down their effective collision radius by an
amount {rfactor}, so that SRD particle will only collide with one big
particle at a time. For example, in a Lennard-Jones system at a
temperature of 1.0 (in reduced LJ units), the minimum separation
bewteen two big particles is as small as about 0.88 sigma. Thus an
{rfactor} value of 0.85 should prevent dual collisions.
The {bounce} keyword can be used to limit the maximum number of
collisions an SRD particle undergoes in a single timestep as it
bounces between nearby big particles. Note that if the limit is
reached, the SRD can be left inside a big particle. A setting of 0 is
the same as no limit.
:line
There are 2 kinds of bins created and maintained when running an SRD
simulation. The first are "SRD bins" which are used to bin SRD
particles and reset their velocities, as discussed above. The second
are "search bins" which are used to identify SRD/big particle
collisions.
The {search} keyword can be used to choose a search bin size for
identifying SRD/big particle collisions. The default is to use the
{hgrid} parameter for SRD bins as the search bin size. Choosing a
smaller or large value may be more efficient, depending on the
problem. But, in a statistical sense, it should not change the
simulation results.
The {cubic} keyword can be used to generate an error or warning when
the bin size chosen by LAMMPS creates SRD bins that are non-cubic or
different than the requested value of {hgrid} by a specified
{tolerance}. Note that using non-cubic SRD bins can lead to
undetermined behavior when rotating the velocities of SRD particles,
hence LAMMPS tries to protect you from this problem.
LAMMPS attempts to set the SRD bin size to exactly {hgrid}. However,
there must be an integer number of bins in each dimension of the
simulation box. Thus the actual bin size will depend on the size and
shape of the overall simulation box. The actual bin size is printed
as part of the SRD output when a simulation begins.
If the actual bin size in non-cubic by an amount exceeding the
tolerance, an error or warning is printed, depending on the style of
the {cubic} keyword. Likewise, if the actual bin size differs from
the requested {hgrid} value by an amount exceeding the tolerance, then
an error or warning is printed. The {tolerance} is a fractional
difference. E.g. a tolerance setting of 0.01 on the shape means that
if the ratio of any 2 bin dimensions exceeds (1 +/- tolerance) then an
error or warning is generated. Similarly, if the ratio of any bin
dimension with {hgrid} exceeds (1 +/- tolerance), then an error or
warning is generated.
IMPORTANT NOTE: The fix srd command can be used with simluations the
size and/or shape of the simulation box changes. This can be due to
non-periodic boundary conditions or the use of fixes such as the "fix
deform"_fix_deform.html or "fix wall/srd"_fix_wall_srd.html commands
to impose a shear on an SRD fluid or an interaction with an external
wall. If the box size changes then the size of SRD bins must be
recalculated every reneighboring. This is not necessary if only the
box shape changes. This re-binning is always done so as to fit an
integer number of bins in the current box dimension, whether it be a
fixed, shrink-wrapped, or periodic boundary, as set by the
"boundary"_boundary.html command. If the box size or shape changes,
then the size of the search bins must be recalculated avery
reneighboring. Note that changing the SRD bin size may alter the
properties of the SRD fluid, such as its viscosity.
The {shift} keyword determines whether the coordinates of SRD
particles are randomly shifted when binned for purposes of rotating
their velocities. When no shifting is performed, SRD particles are
binned and the velocity distribution of the set of SRD particles in
each bin is adjusted via a rotation operator. This is a statistically
valid operation if SRD particles move sufficiently far between
successive rotations. This is determined by their mean-free path
lamda. If lamda is less than 0.6 of the SRD bin size, then shifting
is required. A shift means that all of the SRD particles are shifted
by a vector whose coordinates are chosen randomly in the range \[-1/2
bin size, 1/2 bin size\]. Note that all particles are shifted by the
same vector. The specified random number seed is used to generate
these vectors. This operation sufficiently randomizes which SRD
particles are in the same bin, even if lamda is small.
If the {shift} style is set to {no}, then no shifting is performed,
but bin data will be communicated if bins overlap processor
boundaries. An error will be generated if lamda < 0.6 of the SRD bin
size. If the {shift} style is set to {possible}, then shifting is
performed only if lamda < 0.6 of the SRD bin size. A warning is
generated to let you know this is occurring. If the {shift} style is
set to {yes} then shifting is performed regardless of the magnitude of
lamda.
The shift seed is not used if the {shift} style is set to {no}, but
must still be specified.
Note that shifting of SRD coordinates requires extra communication,
hence it should not normally be enabled unless required.
The {stream} keyword should be used when SRD particles are used with
the "fix deform"_fix_deform.html command to perform a simulation
undergoing shear, e.g. to measure a viscosity. If the {stream} style
is set to {yes}, then the mean velocity of each bin of SRD particles
is set to the streaming velocity of the deforming box, each time SRD
velocities are reset, every N timesteps. If the {stream} style is set
to {no}, then the mean velocity is unchanged, which may mean that it
takes a long time for the SRD fluid to come to equilibrium with a
velocity profile that matches the simulation box deformation.
:line
IMPORTANT NOTE: This fix is normally used for simulations with a huge
number of SRD particles relative to the number of big particles,
e.g. 100 to 1. In this scenario, computations that involve only big
particles (neighbor list creation, communication, time integration)
can slow down dramatically due to the large number of background SRD
particles.
Three other input script commands will largely overcome this effect,
speeding up an SRD simulation by a significant amount. These are the
"atom_modify first"_atom_modify.html, "neigh_modify
include"_neigh_modify.html, and "communicate group"_communicate.html
commands. Each takes a group-ID as an argument, which in this case
should be the group-ID of the big solute particles.
Additionally, when a "pair_style"_pair_style.html for big/big particle
interactions is specified, the "pair_coeff"_pair_coeff.html command
should be used to turn off big/SRD interactions, e.g. by setting their
epsilon or cutoff length to 0.0.
The "delete_atoms overlap" command may be useful in setting up an SRD
simulation to insure there are no initial overlaps between big and SRD
particles.
:line
[Restart, fix_modify, output, run start/stop, minimize info:]
No information about this fix is written to "binary restart
files"_restart.html. None of the "fix_modify"_fix_modify.html options
are relevant to this fix.
This fix tabulates several SRD statistics which are stored in a vector
of length 12, which can be accessed by various "output
commands"_Section_howto.html#4_15. The vector values calculated by
this fix are "intensive", meaning they do not scale with the size of
the simulation. Technically, the first 8 do scale with the size of
the simulation, but treating them as intensive means they are not
scaled when printed as part of thermodyanmic output.
These are the 12 quantities. All are values for the current timestep,
except the last three which are cummulative quantities since the
beginning of the run.
(1) # of SRD/big collision checks performed
(2) # of SRDs which had a collision
(3) # of SRD/big colllisions (including multiple bounces)
(4) # of SRD particles inside a big particle
(5) # of SRD particles whose velocity was rescaled to be < Vmax
(6) # of bins for collision searching
(7) # of bins for SRD velocity rotation
(8) # of bins in which SRD temperature was computed
(9) SRD temperature
(10) # of SRD particles which have undergone max # of bounces
(11) max # of bounces any SRD particle has had in a single step
(12) # of reneighborings dues to SRD particles moving too far :ul
No parameter of this fix can be used with the {start/stop} keywords of
the "run"_run.html command. This fix is not invoked during "energy
minimization"_minimize.html.
-[Restrictions:] none
+[Restrictions:]
This command can only be used if LAMMPS was built with the "srd"
package. See the "Making LAMMPS"_Section_start.html#2_3 section for
more info on packages.
[Related commands:]
"fix wall/srd"_fix_wall_srd.html
[Default:]
The option defaults are lamda inferred from Tsrd, collision = noslip,
overlap = no, inside = error, exact = yes, radius = 1.0, bounce = 0,
search = hgrid, cubic = error 0.01, shift = no, stream = yes.
:line
:link(Hecht)
[(Hecht)] Hecht, Harting, Ihle, Herrmann, Phys Rev E, 72, 011408 (2005).
:link(Petersen)
[(Petersen)] Petersen, Lechman, Plimpton, Grest, in' t Veld, Schunk, J
Chem Phys, 132, 174106 (2010).
-:link(Lechman) [(Lechman)] Lechman, et al, in preparation (2010).
+:link(Lechman)
+[(Lechman)] Lechman, et al, in preparation (2010).
diff --git a/doc/tad.html b/doc/tad.html
index 411809323..29e8b21cb 100644
--- a/doc/tad.html
+++ b/doc/tad.html
@@ -1,317 +1,315 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>tad command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>tad N t_event T_lo T_hi delta tmax compute-ID seed keyword value ...
</PRE>
<UL><LI>N = # of timesteps to run (not including dephasing/quenching)
<LI>t_event = timestep interval between event checks
<LI>T_lo = temperature at which event times are desired
<LI>T_hi = temperature at which MD simulation is performed
<LI>delta = desired confidence level for stopping criterion
<LI>tmax = reciprocal of lowest expected preexponential factor (time units)
<LI>compute-ID = ID of the compute used for event detection
<LI>zero or more keyword/value pairs may be appended
<LI>keyword = <I>min</I> or <I>neb</I> or <I>min_style</I> or <I>neb_style</I> or <I>neb_log</I>
<PRE> <I>min</I> values = etol ftol maxiter maxeval
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
maxiter = max iterations of minimize
maxeval = max number of force/energy evaluations
<I>neb</I> values = ftol N1 N2 Nevery
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
N1 = max # of iterations (timesteps) to run initial NEB
N2 = max # of iterations (timesteps) to run barrier-climbing NEB
Nevery = print NEB statistics every this many timesteps
<I>min_style</I> value = <I>cg</I> or <I>hftn</I> or <I>sd</I> or <I>quickmin</I> or <I>fire</I>
<I>neb_style</I> value = <I>quickmin</I> or <I>fire</I>
<I>neb_log</I> value = file where NEB statistics are printed
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>tad 2000 50 1800 2300 0.01 0.01 event 54985
tad 2000 50 1800 2300 0.01 0.01 event 54985 &
min 1e-05 1e-05 100 100 &
neb 0.0 0.01 200 200 20 &
min_style cg &
neb_style fire &
neb_log log.neb
</PRE>
<P><B>Description:</B>
</P>
<P>Run a temperature accelerated dynamics (TAD) simulation. This method
requires two or more partitions to perform NEB transition state
searches.
</P>
<P>TAD is described in <A HREF = "#Voter">this paper</A> by Art Voter. It is a method
that uses accelerated dynamics at an elevated temperature to generate
results at a specified lower temperature. A good overview of
accelerated dynamics methods for such systems is given in <A HREF = "#Voter2">this review
paper</A> from the same group. In general, these methods assume
that the long-time dynamics is dominated by infrequent events i.e. the
system is is confined to low energy basins for long periods,
punctuated by brief, randomly-occurring transitions to adjacent
basins. TAD is suitable for infrequent-event systems, where in
addition, the transition kinetics are well-approximated by harmonic
transition state theory (hTST). In hTST, the temperature dependence of
transition rates follows the Arrhenius relation. As a consequence a
set of event times generated in a high-temperature simulation can be
mapped to a set of much longer estimated times in the low-temperature
system. However, because this mapping involves the energy barrier of
the transition event, which is different for each event, the first
event at the high temperature may not be the earliest event at the low
temperature. TAD handles this by first generating a set of possible
events from the current basin. After each event, the simulation is
reflected backwards into the current basin. This is repeated until
the stopping criterion is satisfied, at which point the event with the
earliest low-temperature occurrence time is selected. The stopping
criterion is that the confidence measure be greater than
1-<I>delta</I>. The confidence measure is the probability that no earlier
low-temperature event will occur at some later time in the
high-temperature simulation. hTST provides an lower bound for this
probability, based on the user-specified minimum pre-exponential
factor (reciprocal of <I>tmax</I>).
</P>
<P>In order to estimate the energy barrier for each event, the TAD method
invokes the <A HREF = "neb.html">NEB</A> method. Each NEB replica runs on a
partition of processors. The current NEB implementation in LAMMPS
restricts you to having exactly one processor per replica. For more
information, see the documentation for the <A HREF = "neb.html">neb</A> command. In
the current LAMMPS implementation of TAD, all the non-NEB TAD
operations are performed on the first partition, while the other
partitions remain idle. See <A HREF = "Section_howto.html#4_5">this
section</A> of the manual for further discussion
of multi-replica simulations.
</P>
<P>A TAD run has several stages, which are repeated each time an event is
performed. The logic for a TAD run is as follows:
</P>
<PRE>while (time remains):
while (time < tstop):
until (event occurs):
run dynamics for t_event steps
quench
run neb calculation using all replicas
compute tlo from energy barrier
update earliest event
update tstop
reflect back into current basin
execute earliest event
</PRE>
<P>Before this outer loop begins, the initial potential energy basin is
identified by quenching (an energy minimization, see below) the
initial state and storing the resulting coordinates for reference.
</P>
<P>Inside the inner loop, dynamics is run continuously according to
whatever integrator has been specified by the user, stopping every
<I>t_event</I> steps to check if a transition event has occurred. This
check is performed by quenching the system and comparing the resulting
atom coordinates to the coordinates from the previous basin.
</P>
<P>A quench is an energy minimization and is performed by whichever
algorithm has been defined by the <I>min</I> and <I>min_style</I> keywords or
their default values. Note that typically, you do not need to perform
a highly-converged minimization to detect a transition event.
</P>
<P>The event check is performed by a compute with the specified
<I>compute-ID</I>. Currently there is only one compute that works with the
TAD commmand, which is the <A HREF = "compute_event_displace.html">compute
event/displace</A> command. Other
event-checking computes may be added. <A HREF = "compute_event_displace.html">Compute
event/displace</A> checks whether any atom in
the compute group has moved further than a specified threshold
distance. If so, an "event" has occurred.
</P>
<P>The neb calculation is similar to that invoked by the <A HREF = "neb.html">neb</A>
command, except that the final state is generated internally, instead
of being read in from a file. The TAD implementation provides default
values for the NEB settings, which can be overridden using the <I>neb</I>
and <I>neb_style</I> keywords.
</P>
<HR>
<P>A key aspect of the TAD method is setting the stopping criterion
appropriately. If this criterion is too conservative, then many
events must be generated before one is finally executed. Conversely,
if this criterion is too aggressive, high-entropy high-barrier events
will be over-sampled, while low-entropy low-barrier events will be
under-sampled. If the lowest pre-exponential factor is known fairly
accurately, then it can be used to estimate <I>tmax</I>, and the value of
<I>delta</I> can be set to the desired confidence level e.g. <I>delta</I> = 0.05
corresponds to 95% confidence. However, for systems where the dynamics
are not well characterized (the most common case), it will be
necessary to experiment with the values of <I>delta</I> and <I>tmax</I> to get a
good trade-off between accuracy and performance.
</P>
<P>A second key aspect is the choice of <I>t_hi</I>. A larger value greatly
increases the rate at which new events are generated. However, too
large a value introduces errors due to anharmonicity (not accounted
for within hTST). Once again, for any given system, experimentation is
necessary to determine the best value of <I>t_hi</I>.
</P>
<HR>
<P>Five kinds of output can be generated during a TAD run: event
statistics, NEB statistics, thermodynamic output by each replica, dump
files, and restart files.
</P>
<P>Event statistics are printed to the screen and master log.lammps file
each time an event is executed. The quantities are the timestep, CPU
-time, global event number <I>N</I>, local event number <I>M</I>,
-event status, energy barrier, time margin, <I>t_lo</I> and <I>delt_lo</I>.
-The timestep is the usual LAMMPS
-timestep, which corresponds to the high-temperature time at which the
-event was detected, in units of timestep. The CPU time is the total
-processor time since the start of the TAD run.
-The global event number <I>N</I> is a counter
-that increments with each executed event. The local event number <I>M</I>
-is a counter that resets to zero upon entering each new basin.
-The event status is <I>E</I> when an event is executed, and
-is <I>D</I> for an event that is detected, while <I>DF</I> is for a detected
-event that is also the earliest (first) event at the low temperature.
-</P>
-<P>The time margin is the ratio of the high temperature time in the current
-basin to the stopping time. This last number can be used to judge
-whether the stopping time is too short or too long (see above).
-</P>
-<P><I>t_lo</I> is the low-temperature event time when the current basin was entered,
-in units of timestep. del<I>t_lo</I> is the time of each detected
-event, measured relative to <I>t_lo</I>. <I>delt_lo</I>
-is equal to the high-temperature time since entering the current
-basin, scaled by an
+time, global event number <I>N</I>, local event number <I>M</I>, event status,
+energy barrier, time margin, <I>t_lo</I> and <I>delt_lo</I>. The timestep is
+the usual LAMMPS timestep, which corresponds to the high-temperature
+time at which the event was detected, in units of timestep. The CPU
+time is the total processor time since the start of the TAD run. The
+global event number <I>N</I> is a counter that increments with each
+executed event. The local event number <I>M</I> is a counter that resets to
+zero upon entering each new basin. The event status is <I>E</I> when an
+event is executed, and is <I>D</I> for an event that is detected, while
+<I>DF</I> is for a detected event that is also the earliest (first) event
+at the low temperature.
+</P>
+<P>The time margin is the ratio of the high temperature time in the
+current basin to the stopping time. This last number can be used to
+judge whether the stopping time is too short or too long (see above).
+</P>
+<P><I>t_lo</I> is the low-temperature event time when the current basin was
+entered, in units of timestep. del<I>t_lo</I> is the time of each detected
+event, measured relative to <I>t_lo</I>. <I>delt_lo</I> is equal to the
+high-temperature time since entering the current basin, scaled by an
exponential factor that depends on the hi/lo temperature ratio and the
-energy barrier for that event.
+energy barrier for that event.
</P>
-<P>On lines for executed events, with status <I>E</I>, the global event number is
-incremented by one, and the timestep, local event number,
-energy barrier, <I>t_lo</I>, and <I>delt_lo</I> match the last event with status <I>DF</I> in the
-immediately preceding block of detected events.
+<P>On lines for executed events, with status <I>E</I>, the global event number
+is incremented by one, and the timestep, local event number, energy
+barrier, <I>t_lo</I>, and <I>delt_lo</I> match the last event with status <I>DF</I>
+in the immediately preceding block of detected events.
</P>
<P>The NEB statistics are written to the file specified by the <I>neb_log</I>
keyword. If the keyword value is "none", then no NEB statistics are
printed out. The statistics are written every <I>Nevery</I> timesteps. See
the <A HREF = "neb.html">neb</A> command for a full description of the NEB
statistics. When invoked from TAD, NEB statistics are never printed to
the screen.
</P>
<P>Because the NEB calculation must run on multiple partitions, LAMMPS
produces additional screen and log files for each partition,
e.g. log.lammps.0, log.lammps.1, etc. For the TAD command, these
contain the thermodynamic output of each NEB replica. In addition, the
log file for the first partition, log.lammps.0, will contain
thermodynamic output from short runs and minimizations corresponding
to the dynamics and quench operations, as well as a line for each new
detected event, as described above.
</P>
<P>After the TAD command completes, timing statistics for the TAD run are
printed in each replica's log file, giving a breakdown of how much CPU
time was spent in each stage (NEB, dynamics, quenching, etc).
</P>
<P>Any <A HREF = "dump.html">dump files</A> defined in the input script will be written
to during a TAD run at timesteps when an event is executed. This
means the the requested dump frequency in the <A HREF = "dump.html">dump</A> command
is ignored. There will be one dump file (per dump command) created
for all partitions. The atom coordinates of the dump snapshot are
those of the minimum energy configuration resulting from quenching
following the executed event. The timesteps written into the dump
files correspond to the timestep at which the event occurred and NOT
the clock. A dump snapshot corresponding to the initial minimum state
used for event detection is written to the dump file at the beginning
of each TAD run.
</P>
<P>If the <A HREF = "restart.html">restart</A> command is used, a single restart file
for all the partitions is generated, which allows a TAD run to be
continued by a new input script in the usual manner. The restart file
is generated after an event is executed. The restart file contains a
snapshot of the system in the new quenched state, including the event
number and the low-temperature time. The restart frequency specified
in the <A HREF = "restart.html">restart</A> command is interpreted differently when
performing a TAD run. It does not mean the timestep interval between
restart files. Instead it means an event interval for executed
events. Thus a frequency of 1 means write a restart file every time
an event is executed. A frequency of 10 means write a restart file
every 10th executed event. When an input script reads a restart file
from a previous TAD run, the new script can be run on a different
number of replicas or processors.
</P>
<P>Note that within a single state, the dynamics will typically
temporarily continue beyond the event that is ultimately chosen, until
the stopping criterionis satisfied. When the event is eventually
executed, the timestep counter is reset to the value when the event
was detected. Similarly, after each quench and NEB minimization, the
timestep counter is reset to the value at the start of the
minimization. This means that the timesteps listed in the replica log
files do not always increase monotonically. However, the timestep
values printed to the master log file, dump files, and restart files
are always monotonically increasing.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>This command can only be used if LAMMPS was built with the "replica"
package. See the <A HREF = "Section_start.html#2_3">Making LAMMPS</A> section for
more info on packages.
</P>
<P><I>N</I> setting must be integer multiple of <I>t_event</I>.
</P>
<P>Runs restarted from restart files written during a TAD run will only
produce identical results if the user-specified integrator supports
exact restarts. So <A HREF = "fix_nh.html">fix nvt</A> will produce an exact
restart, but <A HREF = "fix_langevin.html">fix langevin</A> will not.
</P>
<P>This command cannot be used when any fixes are defined that keep track
of elapsed time to perform time-dependent operations. Examples
include the "ave" fixes such as <A HREF = "fix_ave_spatial.html">fix
ave/spatial</A>. Also <A HREF = "fix_dt_reset.html">fix
dt/reset</A> and <A HREF = "fix_deposit.html">fix deposit</A>.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "compute_event_displace.html">compute event/displace</A>,
<A HREF = "min_modify.html">min_modify</A>, <A HREF = "min_style.html">min_style</A>,
<A HREF = "run_style.html">run_style</A>, <A HREF = "minimize.html">minimize</A>,
<A HREF = "temper.html">temper</A>, <A HREF = "neb.html">neb</A>,
<A HREF = "prd.html">prd</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are <I>min</I> = 0.1 0.1 40 50, <I>neb</I> = 0.01 100 100
10, <I>min_style</I> = <I>cg</I>, <I>neb_style</I> = <I>quickmin</I>, and <I>neb_log</I> =
"none"
</P>
<HR>
<A NAME = "Voter"></A>
<P><B>(Voter)</B> S�rensen and Voter, J Chem Phys, 112, 9599 (2000)
</P>
<A NAME = "Voter2"></A>
<P><B>(Voter2)</B> Voter, Montalenti, Germann, Annual Review of Materials
Research 32, 321 (2002).
</P>
</HTML>
diff --git a/doc/tad.txt b/doc/tad.txt
index 0e61257f9..a7f9d3088 100644
--- a/doc/tad.txt
+++ b/doc/tad.txt
@@ -1,303 +1,301 @@
"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
tad command :h3
[Syntax:]
tad N t_event T_lo T_hi delta tmax compute-ID \
seed keyword value ... :pre
N = # of timesteps to run (not including dephasing/quenching) :ulb,l
t_event = timestep interval between event checks :l
T_lo = temperature at which event times are desired :l
T_hi = temperature at which MD simulation is performed :l
delta = desired confidence level for stopping criterion :l
tmax = reciprocal of lowest expected preexponential factor (time units) :l
compute-ID = ID of the compute used for event detection :l
zero or more keyword/value pairs may be appended :l
keyword = {min} or {neb} or {min_style} or {neb_style} or {neb_log} :l
{min} values = etol ftol maxiter maxeval
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
maxiter = max iterations of minimize
maxeval = max number of force/energy evaluations
{neb} values = ftol N1 N2 Nevery
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
N1 = max # of iterations (timesteps) to run initial NEB
N2 = max # of iterations (timesteps) to run barrier-climbing NEB
Nevery = print NEB statistics every this many timesteps
{min_style} value = {cg} or {hftn} or {sd} or {quickmin} or {fire}
{neb_style} value = {quickmin} or {fire}
{neb_log} value = file where NEB statistics are printed :pre
:ule
[Examples:]
tad 2000 50 1800 2300 0.01 0.01 event 54985
tad 2000 50 1800 2300 0.01 0.01 event 54985 &
min 1e-05 1e-05 100 100 &
neb 0.0 0.01 200 200 20 &
min_style cg &
neb_style fire &
neb_log log.neb :pre
[Description:]
Run a temperature accelerated dynamics (TAD) simulation. This method
requires two or more partitions to perform NEB transition state
searches.
TAD is described in "this paper"_#Voter by Art Voter. It is a method
that uses accelerated dynamics at an elevated temperature to generate
results at a specified lower temperature. A good overview of
accelerated dynamics methods for such systems is given in "this review
paper"_#Voter2 from the same group. In general, these methods assume
that the long-time dynamics is dominated by infrequent events i.e. the
system is is confined to low energy basins for long periods,
punctuated by brief, randomly-occurring transitions to adjacent
basins. TAD is suitable for infrequent-event systems, where in
addition, the transition kinetics are well-approximated by harmonic
transition state theory (hTST). In hTST, the temperature dependence of
transition rates follows the Arrhenius relation. As a consequence a
set of event times generated in a high-temperature simulation can be
mapped to a set of much longer estimated times in the low-temperature
system. However, because this mapping involves the energy barrier of
the transition event, which is different for each event, the first
event at the high temperature may not be the earliest event at the low
temperature. TAD handles this by first generating a set of possible
events from the current basin. After each event, the simulation is
reflected backwards into the current basin. This is repeated until
the stopping criterion is satisfied, at which point the event with the
earliest low-temperature occurrence time is selected. The stopping
criterion is that the confidence measure be greater than
1-{delta}. The confidence measure is the probability that no earlier
low-temperature event will occur at some later time in the
high-temperature simulation. hTST provides an lower bound for this
probability, based on the user-specified minimum pre-exponential
factor (reciprocal of {tmax}).
In order to estimate the energy barrier for each event, the TAD method
invokes the "NEB"_neb.html method. Each NEB replica runs on a
partition of processors. The current NEB implementation in LAMMPS
restricts you to having exactly one processor per replica. For more
information, see the documentation for the "neb"_neb.html command. In
the current LAMMPS implementation of TAD, all the non-NEB TAD
operations are performed on the first partition, while the other
partitions remain idle. See "this
section"_Section_howto.html#4_5 of the manual for further discussion
of multi-replica simulations.
A TAD run has several stages, which are repeated each time an event is
performed. The logic for a TAD run is as follows:
while (time remains):
while (time < tstop):
until (event occurs):
run dynamics for t_event steps
quench
run neb calculation using all replicas
compute tlo from energy barrier
update earliest event
update tstop
reflect back into current basin
execute earliest event :pre
Before this outer loop begins, the initial potential energy basin is
identified by quenching (an energy minimization, see below) the
initial state and storing the resulting coordinates for reference.
Inside the inner loop, dynamics is run continuously according to
whatever integrator has been specified by the user, stopping every
{t_event} steps to check if a transition event has occurred. This
check is performed by quenching the system and comparing the resulting
atom coordinates to the coordinates from the previous basin.
A quench is an energy minimization and is performed by whichever
algorithm has been defined by the {min} and {min_style} keywords or
their default values. Note that typically, you do not need to perform
a highly-converged minimization to detect a transition event.
The event check is performed by a compute with the specified
{compute-ID}. Currently there is only one compute that works with the
TAD commmand, which is the "compute
event/displace"_compute_event_displace.html command. Other
event-checking computes may be added. "Compute
event/displace"_compute_event_displace.html checks whether any atom in
the compute group has moved further than a specified threshold
distance. If so, an "event" has occurred.
The neb calculation is similar to that invoked by the "neb"_neb.html
command, except that the final state is generated internally, instead
of being read in from a file. The TAD implementation provides default
values for the NEB settings, which can be overridden using the {neb}
and {neb_style} keywords.
:line
A key aspect of the TAD method is setting the stopping criterion
appropriately. If this criterion is too conservative, then many
events must be generated before one is finally executed. Conversely,
if this criterion is too aggressive, high-entropy high-barrier events
will be over-sampled, while low-entropy low-barrier events will be
under-sampled. If the lowest pre-exponential factor is known fairly
accurately, then it can be used to estimate {tmax}, and the value of
{delta} can be set to the desired confidence level e.g. {delta} = 0.05
corresponds to 95% confidence. However, for systems where the dynamics
are not well characterized (the most common case), it will be
necessary to experiment with the values of {delta} and {tmax} to get a
good trade-off between accuracy and performance.
A second key aspect is the choice of {t_hi}. A larger value greatly
increases the rate at which new events are generated. However, too
large a value introduces errors due to anharmonicity (not accounted
for within hTST). Once again, for any given system, experimentation is
necessary to determine the best value of {t_hi}.
:line
Five kinds of output can be generated during a TAD run: event
statistics, NEB statistics, thermodynamic output by each replica, dump
files, and restart files.
Event statistics are printed to the screen and master log.lammps file
each time an event is executed. The quantities are the timestep, CPU
-time, global event number {N}, local event number {M},
-event status, energy barrier, time margin, {t_lo} and {delt_lo}.
-The timestep is the usual LAMMPS
-timestep, which corresponds to the high-temperature time at which the
-event was detected, in units of timestep. The CPU time is the total
-processor time since the start of the TAD run.
-The global event number {N} is a counter
-that increments with each executed event. The local event number {M}
-is a counter that resets to zero upon entering each new basin.
-The event status is {E} when an event is executed, and
-is {D} for an event that is detected, while {DF} is for a detected
-event that is also the earliest (first) event at the low temperature.
+time, global event number {N}, local event number {M}, event status,
+energy barrier, time margin, {t_lo} and {delt_lo}. The timestep is
+the usual LAMMPS timestep, which corresponds to the high-temperature
+time at which the event was detected, in units of timestep. The CPU
+time is the total processor time since the start of the TAD run. The
+global event number {N} is a counter that increments with each
+executed event. The local event number {M} is a counter that resets to
+zero upon entering each new basin. The event status is {E} when an
+event is executed, and is {D} for an event that is detected, while
+{DF} is for a detected event that is also the earliest (first) event
+at the low temperature.
-The time margin is the ratio of the high temperature time in the current
-basin to the stopping time. This last number can be used to judge
-whether the stopping time is too short or too long (see above).
-
-{t_lo} is the low-temperature event time when the current basin was entered,
-in units of timestep. del{t_lo} is the time of each detected
-event, measured relative to {t_lo}. {delt_lo}
-is equal to the high-temperature time since entering the current
-basin, scaled by an
+The time margin is the ratio of the high temperature time in the
+current basin to the stopping time. This last number can be used to
+judge whether the stopping time is too short or too long (see above).
+
+{t_lo} is the low-temperature event time when the current basin was
+entered, in units of timestep. del{t_lo} is the time of each detected
+event, measured relative to {t_lo}. {delt_lo} is equal to the
+high-temperature time since entering the current basin, scaled by an
exponential factor that depends on the hi/lo temperature ratio and the
-energy barrier for that event.
+energy barrier for that event.
-On lines for executed events, with status {E}, the global event number is
-incremented by one, and the timestep, local event number,
-energy barrier, {t_lo}, and {delt_lo} match the last event with status {DF} in the
-immediately preceding block of detected events.
+On lines for executed events, with status {E}, the global event number
+is incremented by one, and the timestep, local event number, energy
+barrier, {t_lo}, and {delt_lo} match the last event with status {DF}
+in the immediately preceding block of detected events.
The NEB statistics are written to the file specified by the {neb_log}
keyword. If the keyword value is "none", then no NEB statistics are
printed out. The statistics are written every {Nevery} timesteps. See
the "neb"_neb.html command for a full description of the NEB
statistics. When invoked from TAD, NEB statistics are never printed to
the screen.
Because the NEB calculation must run on multiple partitions, LAMMPS
produces additional screen and log files for each partition,
e.g. log.lammps.0, log.lammps.1, etc. For the TAD command, these
contain the thermodynamic output of each NEB replica. In addition, the
log file for the first partition, log.lammps.0, will contain
thermodynamic output from short runs and minimizations corresponding
to the dynamics and quench operations, as well as a line for each new
detected event, as described above.
After the TAD command completes, timing statistics for the TAD run are
printed in each replica's log file, giving a breakdown of how much CPU
time was spent in each stage (NEB, dynamics, quenching, etc).
Any "dump files"_dump.html defined in the input script will be written
to during a TAD run at timesteps when an event is executed. This
means the the requested dump frequency in the "dump"_dump.html command
is ignored. There will be one dump file (per dump command) created
for all partitions. The atom coordinates of the dump snapshot are
those of the minimum energy configuration resulting from quenching
following the executed event. The timesteps written into the dump
files correspond to the timestep at which the event occurred and NOT
the clock. A dump snapshot corresponding to the initial minimum state
used for event detection is written to the dump file at the beginning
of each TAD run.
If the "restart"_restart.html command is used, a single restart file
for all the partitions is generated, which allows a TAD run to be
continued by a new input script in the usual manner. The restart file
is generated after an event is executed. The restart file contains a
snapshot of the system in the new quenched state, including the event
number and the low-temperature time. The restart frequency specified
in the "restart"_restart.html command is interpreted differently when
performing a TAD run. It does not mean the timestep interval between
restart files. Instead it means an event interval for executed
events. Thus a frequency of 1 means write a restart file every time
an event is executed. A frequency of 10 means write a restart file
every 10th executed event. When an input script reads a restart file
from a previous TAD run, the new script can be run on a different
number of replicas or processors.
Note that within a single state, the dynamics will typically
temporarily continue beyond the event that is ultimately chosen, until
the stopping criterionis satisfied. When the event is eventually
executed, the timestep counter is reset to the value when the event
was detected. Similarly, after each quench and NEB minimization, the
timestep counter is reset to the value at the start of the
minimization. This means that the timesteps listed in the replica log
files do not always increase monotonically. However, the timestep
values printed to the master log file, dump files, and restart files
are always monotonically increasing.
:line
[Restrictions:]
This command can only be used if LAMMPS was built with the "replica"
package. See the "Making LAMMPS"_Section_start.html#2_3 section for
more info on packages.
{N} setting must be integer multiple of {t_event}.
Runs restarted from restart files written during a TAD run will only
produce identical results if the user-specified integrator supports
exact restarts. So "fix nvt"_fix_nh.html will produce an exact
restart, but "fix langevin"_fix_langevin.html will not.
This command cannot be used when any fixes are defined that keep track
of elapsed time to perform time-dependent operations. Examples
include the "ave" fixes such as "fix
ave/spatial"_fix_ave_spatial.html. Also "fix
dt/reset"_fix_dt_reset.html and "fix deposit"_fix_deposit.html.
[Related commands:]
"compute event/displace"_compute_event_displace.html,
"min_modify"_min_modify.html, "min_style"_min_style.html,
"run_style"_run_style.html, "minimize"_minimize.html,
"temper"_temper.html, "neb"_neb.html,
"prd"_prd.html
[Default:]
The option defaults are {min} = 0.1 0.1 40 50, {neb} = 0.01 100 100
10, {min_style} = {cg}, {neb_style} = {quickmin}, and {neb_log} =
"none"
:line
:link(Voter)
[(Voter)] S�rensen and Voter, J Chem Phys, 112, 9599 (2000)
:link(Voter2)
[(Voter2)] Voter, Montalenti, Germann, Annual Review of Materials
Research 32, 321 (2002).
diff --git a/doc/variable.html b/doc/variable.html
index 65c519b43..ec3f1c857 100644
--- a/doc/variable.html
+++ b/doc/variable.html
@@ -1,861 +1,861 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>variable command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>variable name style args ...
</PRE>
<UL><LI>name = name of variable to define
<LI>style = <I>delete</I> or <I>index</I> or <I>loop</I> or <I>world</I> or <I>universe</I> or <I>uloop</I> or <I>string</I> or <I>equal</I> or <I>atom</I>
<PRE> <I>delete</I> = no args
<I>index</I> args = one or more strings
<I>loop</I> args = N
N = integer size of loop, loop from 1 to N inclusive
<I>loop</I> args = N pad
N = integer size of loop, loop from 1 to N inclusive
pad = all values will be same length, e.g. 001, 002, ..., 100
<I>loop</I> args = N1 N2
N1,N2 = loop from N1 to N2 inclusive
<I>loop</I> args = N1 N2 pad
N1,N2 = loop from N1 to N2 inclusive
pad = all values will be same length, e.g. 050, 051, ..., 100
<I>world</I> args = one string for each partition of processors
<I>universe</I> args = one or more strings
<I>uloop</I> args = N
N = integer size of loop
<I>uloop</I> args = N pad
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
<I>string</I> arg = one string
<I>equal</I> or <I>atom</I> args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
constants = PI
thermo keywords = vol, ke, press, etc from <A HREF = "thermo_style.html">thermo_style</A>
math operators = (), -x, x+y, x-y, x*y, x/y, x^y,
x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y, !x
math functions = sqrt(x), exp(x), ln(x), log(x),
sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x),
random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x)
ramp(x,y), stagger(x,y), logfreq(x,y,z), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)
group functions = count(group), mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,xmin), gyration(group), ke(group),
angmom(group,dim), torque(group,dim),
inertia(group,dimdim), omega(group,dim)
region functions = count(group,region), mass(group,region), charge(group,region),
xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region),
bound(group,xmin,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y)
atom value = mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i]
atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz
compute references = c_ID, c_ID[i], c_ID[i][j]
fix references = f_ID, f_ID[i], f_ID[i][j]
variable references = v_name, v_name[i]
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop $n
variable beta equal temp/3.0
variable b1 equal x[234]+0.5*vol
variable b1 equal "x[234] + 0.5*vol"
variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
variable b atom x*y/vol
variable foo myfile
variable temp world 300.0 310.0 320.0 ${Tfinal}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15 pad
variable x delete
</PRE>
<P><B>Description:</B>
</P>
<P>This command assigns one or more strings to a variable name for
evaluation later in the input script or during a simulation.
</P>
<P>Variables can be used in several ways in LAMMPS. A variable can be
referenced elsewhere in an input script to become part of a new input
command. For variable styles that store multiple strings, the
<A HREF = "next.html">next</A> command can be used to increment which string is
assigned to the variable. Variables of style <I>equal</I> store a formula
which when evaluated produces a single numeric value which can be
output either directly (see the <A HREF = "print.html">print</A>, <A HREF = "fix_print.html">fix
print</A>, and <A HREF = "run.html">run every</A> commands) or as part
of thermodynamic output (see the <A HREF = "thermo_style.html">thermo_style</A>
command), or used as input to an averaging fix (see the <A HREF = "fix_ave_time.html">fix
ave/time</A> command). Variables of style <I>atom</I> store
a formula which when evaluated produces one numeric value per atom
which can be output to a dump file (see the <A HREF = "dump.html">dump custom</A>
command) or used as input to an averaging fix (see the <A HREF = "fix_ave_spatial.html">fix
ave/spatial</A> and <A HREF = "fix_ave_atom.html">fix ave/atom</A>
commands).
</P>
<P>In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
This name can only contain alphanumeric characters and underscores.
The "string" is one or more of the subsequent arguments. The "string"
can be simple text as in the 1st example above, it can contain other
variables as in the 2nd example, or it can be a formula as in the 3rd
example. The "value" is the numeric quantity resulting from
evaluation of the string. Note that the same string can generate
different values when it is evaluated at different times during a
simulation.
</P>
<P>IMPORTANT NOTE: When the input script line that defines a variable of
style <I>equal</I> or <I>atom</I> that contain a formula is encountered, the
formula is NOT immediately evaluated and the result stored. See the
discussion below about "Immediate Evaluation of Variables" if you want
to do this.
</P>
<P>IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
is ignored. This means variables can NOT be re-defined in an input
script (with 2 exceptions, read further). This is to allow an input
script to be processed multiple times without resetting the variables;
see the <A HREF = "jump.html">jump</A> or <A HREF = "include.html">include</A> commands. It also
means that using the <A HREF = "Section_start.html#2_6">command-line switch</A> -var
will override a corresponding index variable setting in the input
script.
</P>
<P>There are two exceptions to this rule. First, variables of style
<I>string</I> and <I>equal</I> and <I>atom</I> ARE redefined each time the command is
encountered. This allows these style of variables to be redefined
multiple times in an input script. In a loop, this means the formula
associated with an <I>equal</I> or <I>atom</I> style variable can change if it
contains a substitution for another variable, e.g. $x.
</P>
<P>Second, as described below, if a variable is iterated on to the end of
its list of strings via the <A HREF = "next.html">next</A> command, it is removed
from the list of active variables, and is thus available to be
re-defined in a subsequent variable command. The <I>delete</I> style does
the same thing.
</P>
<HR>
<P><A HREF = "Section_commands.html#3_2">This section</A> of the manual explains how
occurrences of a variable name in an input script line are replaced by
the variable's string. The variable name can be referenced as $x if
the name "x" is a single character, or as ${LoopVar} if the name
"LoopVar" is one or more characters.
</P>
<P>As described below, for variable styles <I>index</I>, <I>loop</I>, <I>universe</I>,
and <I>uloop</I>, which string is assigned to a variable can be incremented
via the <A HREF = "next.html">next</A> command. When there are no more strings to
assign, the variable is exhausted and a flag is set that causes the
next <A HREF = "jump.html">jump</A> command encountered in the input script to be
skipped. This enables the construction of simple loops in the input
script that are iterated over and then exited from.
</P>
<P>As explained above, an exhausted variable can be re-used in an input
script. The <I>delete</I> style also removes the variable, the same as if
it were exhausted, allowing it to be redefined later in the input
script or when the input script is looped over. This can be useful
when breaking out of a loop via the <A HREF = "if.html">if</A> and <A HREF = "jump.html">jump</A>
commands before the variable would become exhausted. For example,
</P>
<PRE>label loop
variable a loop 5
print "A = $a"
-if $a > 2 then "jump in.script break"
+if "$a > 2" then "jump in.script break"
next a
jump in.script loop
label break
variable a delete
</PRE>
<HR>
<P>For the <I>index</I> style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
<A HREF = "next.html">next</A> command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
</P>
<P><I>Index</I> style variables with a single string value can also be set by
using the command-line switch -var; see <A HREF = "Section_start.html#2_6">this
section</A> for details.
</P>
<P>The <I>loop</I> style is identical to the <I>index</I> style except that the
strings are the integers from 1 to N inclusive, if only one argument N
is specified. This allows generation of a long list of runs
(e.g. 1000) without having to list N strings in the input script.
Initially, the string "1" is assigned to the variable. Each time a
<A HREF = "next.html">next</A> command is used with the variable name, the next
string ("2", "3", etc) is assigned. All processors assign the same
string to the variable. The <I>loop</I> style can also be specified with
two arguments N1 and N2. In this case the loop runs from N1 to N2
inclusive, and the string N1 is initially assigned to the variable.
</P>
<P>For the <I>world</I> style, one or more strings are specified. There must
be one string for each processor partition or "world". See <A HREF = "Section_start.html#2_6">this
section</A> of the manual for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command assigns one string to each
world. All processors in the world are assigned the same string. The
next command cannot be used with <I>equal</I> style variables, since there
is only one value per world. This style of variable is useful when
you wish to run different simulations on different partitions, or when
performing a parallel tempering simulation (see the
<A HREF = "temper.html">temper</A> command), to assign different temperatures to
different partitions.
</P>
<P>For the <I>universe</I> style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". See <A HREF = "Section_start.html#2_6">this page</A> for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command initially assigns one
string to each world. When a <A HREF = "next.html">next</A> command is encountered
using this variable, the first processor partition to encounter it, is
assigned the next available string. This continues until all the
variable strings are consumed. Thus, this command can be used to run
50 simulations on 8 processor partitions. The simulations will be run
one after the other on whatever partition becomes available, until
they are all finished. <I>Universe</I> style variables are incremented
using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock"
which you will see in your directory during such a LAMMPS run.
</P>
<P>The <I>uloop</I> style is identical to the <I>universe</I> style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
</P>
<HR>
<P>For the <I>equal</I> and <I>atom</I> styles, a single string is specified which
represents a formula that will be evaluated afresh each time the
variable is used. If you want spaces in the string, enclose it in
double quotes so the parser will treat it as a single argument. For
<I>equal</I> style variables the formula computes a scalar quantity, which
becomes the value of the variable whenever it is evaluated. For
<I>atom</I> style variables the formula computes one quantity for each
atom whenever it is evaluated.
</P>
<P>Note that <I>equal</I> and <I>atom</I> variables can produce different values at
different stages of the input script or at different times during a
run. For example, if an <I>equal</I> variable is used in a <A HREF = "fix_print.html">fix
print</A> command, different values could be printed each
timestep it was invoked. If you want a variable to be evaluated
immediately, so that the result is stored by the variable instead of
the string, see the section below on "Immediate Evaluation of
Variables".
</P>
<P>The next command cannot be used with <I>equal</I> or <I>atom</I> style
variables, since there is only one string.
</P>
<P>The formula for an <I>equal</I> or <I>atom</I> variable can contain a variety
of quantities. The syntax for each kind of quantity is simple, but
multiple quantities can be nested and combined in various ways to
build up formulas of arbitrary complexity. For example, this is a
valid (though strange) variable formula:
</P>
<PRE>variable x equal "pe + c_MyTemp / vol^(1/3)"
</PRE>
<P>Specifically, an formula can contain numbers, thermo keywords, math
operators, math functions, group functions, region functions, atom
values, atom vectors, compute references, fix references, and
references to other variables.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >Number</TD><TD > 0.2, 100, 1.0e20, -15.4, etc</TD></TR>
<TR><TD >Constant</TD><TD > PI</TD></TR>
<TR><TD >Thermo keywords</TD><TD > vol, pe, ebond, etc</TD></TR>
<TR><TD >Math operators</TD><TD > (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y, !x</TD></TR>
<TR><TD >Math functions</TD><TD > sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)</TD></TR>
<TR><TD >Group functions</TD><TD > count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID), angmom(ID,dim), torque(ID,dim), inertia(ID,dimdim), omega(ID,dim)</TD></TR>
<TR><TD >Region functions</TD><TD > count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR)</TD></TR>
<TR><TD >Special functions</TD><TD > sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y)</TD></TR>
<TR><TD >Atom values</TD><TD > mass[i], type[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i]</TD></TR>
<TR><TD >Atom vectors</TD><TD > mass, type, x, y, z, vx, vy, vz, fx, fy, fz</TD></TR>
<TR><TD >Compute references</TD><TD > c_ID, c_ID[i], c_ID[i][j]</TD></TR>
<TR><TD >Fix references</TD><TD > f_ID, f_ID[i], f_ID[i][j]</TD></TR>
<TR><TD >Other variables</TD><TD > v_name, v_name[i]
</TD></TR></TABLE></DIV>
<HR>
<P>Most of the formula elements produce a scalar value. A few produce a
per-atom vector of values. These are the atom vectors, compute
references that represent a per-atom vector, fix references that
represent a per-atom vector, and variables that are atom-style
variables. Math functions that operate on scalar values produce a
scalar value; math function that operate on per-atom vectors do so
element-by-element and produce a per-atom vector.
</P>
<P>A formula for equal-style variables cannot use any formula element
that produces a per-atom vector. A formula for an atom-style variable
can use formula elements that produce either a scalar value or a
per-atom vector.
</P>
<P>The thermo keywords allowed in a formula are those defined by the
<A HREF = "thermo_style.html">thermo_style custom</A> command. Thermo keywords that
require a <A HREF = "compute.html">compute</A> to calculate their values such as
"temp" or "press", use computes stored and invoked by the
<A HREF = "thermo_style.html">thermo_style</A> command. This means that you can
only use those keywords in a variable if the style you are using with
the thermo_style command (and the thermo keywords associated with that
style) also define and use the needed compute. Note that some thermo
keywords use a compute indirectly to calculate their value (e.g. the
enthalpy keyword uses temp, pe, and pressure). If a variable is
evaluated directly in an input script (not during a run), then the
values accessed by the thermo keyword must be current. See the
discussion below about "Variable Accuracy".
</P>
<HR>
<H4>Math Operators
</H4>
<P>Math operators are written in the usual way, where the "x" and "y" in
the examples can themselves be arbitrarily complex formulas, as in the
examples above. In this syntax, "x" and "y" can be scalar values or
per-atom vectors. For example, "ke/natoms" is the division of two
scalars, where "vy+vz" is the element-by-element sum of two per-atom
vectors of y and z velocities.
</P>
<P>Operators are evaluated left to right and have the usual C-style
precedence: unary minus and unary logical NOT operator "!" have the
highest precedence, exponentiation "^" is next; multiplication and
division are next; addition and subtraction are next; the 4 relational
operators "<", "<=", ">", and ">=" are next; the two remaining
relational operators "==" and "!=" are next; then the logical AND
operator "&&"; and finally the logical OR operator "||" has the lowest
precedence. Parenthesis can be used to group one or more portions of
a formula and/or enforce a different order of evaluation than what
would occur with the default precedence.
</P>
<P>The 6 relational operators return either a 1.0 or 0.0 depending on
whether the relationship between x and y is TRUE or FALSE. For
example the expression x<10.0 in an atom-style variable formula will
return 1.0 for all atoms whose x-coordinate is less than 10.0, and 0.0
for the others. The logical AND operator will return 1.0 if both its
arguments are non-zero, else it returns 0.0. The logical OR operator
will return 1.0 if either of its arguments is non-zero, else it
returns 0.0. The logical NOT operator returns 1.0 if its argument is
0.0, else it returns 0.0.
</P>
<P>These relational and logical operators can be used as a masking or
selection operation in a formula. For example, the number of atoms
whose properties satifsy one or more criteria could be calculated by
taking the returned per-atom vector of ones and zeroes and passing it
to the <A HREF = "compute_reduce.html">compute reduce</A> command.
</P>
<HR>
<H4>Math Functions
</H4>
<P>Math functions are specified as keywords followed by one or more
parenthesized arguments "x", "y", "z", each of which can themselves be
arbitrarily complex formulas. In this syntax, the arguments can
represent scalar values or per-atom vectors. In the latter case, the
math operation is performed on each element of the vector. For
example, "sqrt(natoms)" is the sqrt() of a scalar, where "sqrt(y*z)"
yields a per-atom vector with each element being the sqrt() of the
product of one atom's y and z coordinates.
</P>
<P>Most of the math functions perform obvious operations. The ln() is
the natural log; log() is the base 10 log.
</P>
<P>The random(x,y,z) function takes 3 arguments: x = lo, y = hi, and z =
seed. It generates a uniform random number between lo and hi. The
normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and
z = seed. It generates a Gaussian variate centered on mu with
variance sigma^2. In both cases the seed is used the first time the
internal random number generator is invoked, to initialize it. For
equal-style variables, every processor uses the same seed so that they
each generate the same sequence of random numbers. For atom-style
variables, a unique seed is created for each processor, based on the
specified seed. This effectively generates a different random number
for each atom being looped over in the atom-style variable.
</P>
<P>IMPORTANT NOTE: Internally, there is just one random number generator
for all equal-style variables and one for all atom-style variables.
If you define multiple variables (of each style) which use the
random() or normal() math functions, then the internal random number
generators will only be initialized once, which means only one of the
specified seeds will determine the sequence of generated random
numbers.
</P>
<P>The ceil(), floor(), and round() functions are those in the C math
library. Ceil() is the smallest integer not less than its argument.
Floor() if the largest integer not greater than its argument. Round()
is the nearest integer to its argument.
</P>
<P>The ramp(x,y) function uses the current timestep to generate a value
linearly intepolated between the specified x,y values over the course
of a run, according to this formula:
</P>
<PRE>value = x + (y-x) * (timestep-startstep) / (stopstep-startstep)
</PRE>
<P>The run begins on startstep and ends on stopstep. Startstep and
stopstep can span multiple runs, using the <I>start</I> and <I>stop</I> keywords
of the <A HREF = "run.html">run</A> command. See the <A HREF = "run.html">run</A> command for
details of how to do this.
</P>
<P>The stagger(x,y) function uses the current timestep to generate a new
timestep. X,y > 0 and x > y is required. The generated timesteps
increase in a staggered fashion, as the sequence
x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next
timestep in the sequence is returned. Thus if stagger(1000,100) is
used in a variable by the <A HREF = "dump_modify.html">dump_modify every</A>
command, it will generate the sequence of output timesteps:
</P>
<PRE>100,1000,1100,2000,2100,3000,etc
</PRE>
<P>The logfreq(x,y,z) function uses the current timestep to generate a
new timestep. X,y,z > 0 and y < z is required. The generated
timesteps increase in a logarithmic fashion, as the sequence
x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any
current timestep, the next timestep in the sequence is returned. Thus
if logfreq(100,4,10) is used in a variable by the <A HREF = "dump_modify.html">dump_modify
every</A> command, it will generate the sequence of
output timesteps:
</P>
<PRE>100,200,300,400,1000,2000,3000,4000,10000,20000,etc
</PRE>
<P>The vdisplace(x,y) function takes 2 arguments: x = coord0 and y =
velocity, and uses the elapsed time to change the coordinate value by
a linear displacement due to the applied velocity over the course of a
run, according to this formula:
</P>
<PRE>value = coord0 + velocity*(timestep-startstep)*dt
</PRE>
<P>where dt = the timestep size.
</P>
<P>The run begins on startstep. Startstep can span multiple runs, using
the <I>start</I> keyword of the <A HREF = "run.html">run</A> command. See the
<A HREF = "run.html">run</A> command for details of how to do this. Note that the
<A HREF = "thermo_style.html">thermo_style</A> keyword elaplong =
timestep-startstep.
</P>
<P>The swiggle(x,y,z) and cwiggle(x,y,z) functions each take 3 arguments:
x = coord0, y = amplitude, z = period. They use the elapsed time to
oscillate the coordinate value by a sin() or cos() function over the
course of a run, according to one of these formulas, where
omega = 2 PI / period:
</P>
<PRE>value = coord0 + Amplitude * sin(omega*(timestep-startstep)*dt)
value = coord0 + Amplitude * (1 - cos(omega*(timestep-startstep)*dt))
</PRE>
<P>where dt = the timestep size.
</P>
<P>The run begins on startstep. Startstep can span multiple runs, using
the <I>start</I> keyword of the <A HREF = "run.html">run</A> command. See the
<A HREF = "run.html">run</A> command for details of how to do this. Note that the
<A HREF = "thermo_style.html">thermo_style</A> keyword elaplong =
timestep-startstep.
</P>
<HR>
<H4>Group and Region Functions
</H4>
<P>Group functions are specified as keywords followed by one or two
parenthesized arguments. The first argument is the group-ID. The
<I>dim</I> argument, if it exists, is <I>x</I> or <I>y</I> or <I>z</I>. The <I>dir</I>
argument, if it exists, is <I>xmin</I>, <I>xmax</I>, <I>ymin</I>, <I>ymax</I>, <I>zmin</I>, or
<I>zmax</I>. The <I>dimdim</I> argument, if it exists, is <I>xx</I> or <I>yy</I> or <I>zz</I>
or <I>xy</I> or <I>yz</I> or <I>xz</I>.
</P>
<P>The group function count() is the number of atoms in the group. The
group functions mass() and charge() are the total mass and charge of
the group. Xcm() and vcm() return components of the position and
velocity of the center of mass of the group. Fcm() returns a
component of the total force on the group of atoms. Bound() returns
the min/max of a particular coordinate for all atoms in the group.
Gyration() computes the radius-of-gyration of the group of atoms. See
the <A HREF = "compute_gyration.html">compute gyration</A> command for a definition
of the formula. Angmom() returns components of the angular momentum
of the group of atoms around its center of mass. Torque() returns
components of the torque on the group of atoms around its center of
mass, based on current forces on the atoms. Inertia() returns one of
6 components of the inertia tensor of the group of atoms around its
center of mass. Omega() returns components of the angular velocity of
the group of atoms around its center of mass.
</P>
<P>Region functions are specified exactly the same way as group functions
except they take an extra argument which is the region ID. The
function is computed for all atoms that are in both the group and the
region. If the group is "all", then the only criteria for atom
inclusion is that it be in the region.
</P>
<HR>
<H4>Special Functions
</H4>
<P>Special functions take specific kinds of arguments, meaning their
arguments cannot be formulas themselves.
</P>
<P>The sum(x), min(x), max(x), ave(x), and trap(x) functions each take 1
argument which is of the form "c_ID" or "c_ID[N]" or "f_ID" or
"f_ID[N]". The first two are computes and the second two are fixes;
the ID in the reference should be replaced by the ID of a compute or
fix defined elsewhere in the input script. The compute or fix must
produce either a global vector or array. If it produces a global
vector, then the notation without "[N]" should be used. If it
produces a global array, then the notation with "[N]" should be
used, when N is an integer, to specify which column of the global
array is being referenced.
</P>
<P>These functions operate on the global vector of inputs and reduce it
to a single scalar value. This is analagous to the operation of the
<A HREF = "compute_reduce.html">compute reduce</A> command, which invokes the same
functions on per-atom and local vectors.
</P>
<P>The sum() function calculates the sum of all the vector elements. The
min() and max() functions find the minimum and maximum element
respectively. The ave() function is the same as sum() except that it
divides the result by the length of the vector. The trap() function
is the same as sum() except the first and last elements are multiplied
by a weighting factor of 1/2 when performing the sum. This
effectively implements an integratiion via the trapezoidal rule on the
global vector of data. I.e. consider a set of points, equally spaced
by 1 in their x coordinate: (1,V1), (2,V2), ..., (N,VN), where the Vi
are the values in the global vector of length N. The integral from 1
to N of these points is trap(). When appropriately normalized by the
timestep size, this function is useful for calculating integrals of
time-series data, like that generated by the <A HREF = "fix_ave_correlate.html">fix
ave/correlate</A> command.
</P>
<P>The gmask(x) function takes 1 argument which is a group ID. It
can only be used in atom-style variables. It returns a 1 for
atoms that are in the group, and a 0 for atoms that are not.
</P>
<P>The rmask(x) function takes 1 argument which is a region ID. It can
only be used in atom-style variables. It returns a 1 for atoms that
are in the geometric region, and a 0 for atoms that are not.
</P>
<P>The grmask(x,y) function takes 2 arguments. The first is a group ID,
and the second is a region ID. It can only be used in atom-style
variables. It returns a 1 for atoms that are in both the group and
region, and a 0 for atoms that are not in both.
</P>
<HR>
<H4>Atom Values and Vectors
</H4>
<P>Atom values take a single integer argument I from 1 to N, where I is
the an atom-ID, e.g. x[243], which means use the x coordinate of the
atom with ID = 243.
</P>
<P>Atom vectors generate one value per atom, so that a reference like
"vx" means the x-component of each atom's velocity will be used when
evaluating the variable. Note that other atom attributes can be used
as inputs to a variable by using the <A HREF = "compute_property_atom.html">compute
property/atom</A> command and then specifying
a quantity from that compute.
</P>
<HR>
<H4>Compute References
</H4>
<P>Compute references access quantities calculated by a
<A HREF = "compute.html">compute</A>. The ID in the reference should be replaced by
the ID of a compute defined elsewhere in the input script. As
discussed in the doc page for the <A HREF = "compute.html">compute</A> command,
computes can produce global, per-atom, or local values. Only global
and per-atom values can be used in a variable. Computes can also
produce a scalar, vector, or array. An equal-style variable can only
use scalar values, which means a global scalar, or an element of a
global or per-atom vector or array. Atom-style variables can use the
same scalar values. They can also use per-atom vector values. A
vector value can be a per-atom vector itself, or a column of an
per-atom array. See the doc pages for individual computes to see what
kind of values they produce.
</P>
<P>Examples of different kinds of compute references are as follows.
There is no ambiguity as to what a reference means, since computes
only produce global or per-atom quantities, never both.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >c_ID</TD><TD > global scalar, or per-atom vector</TD></TR>
<TR><TD >c_ID[I]</TD><TD > Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array</TD></TR>
<TR><TD >c_ID[I][J]</TD><TD > I,J element of global array, or atom I's Jth value in per-atom array
</TD></TR></TABLE></DIV>
<P>If a variable containing a compute is evaluated
directly in an input script (not during a run), then the values
accessed by the compute must be current. See the discussion below
about "Variable Accuracy".
</P>
<HR>
<H4>Fix References
</H4>
<P>Fix references access quantities calculated by a <A HREF = "compute.html">fix</A>.
The ID in the reference should be replaced by the ID of a fix defined
elsewhere in the input script. As discussed in the doc page for the
<A HREF = "fix.html">fix</A> command, fixes can produce global, per-atom, or local
values. Only global and per-atom values can be used in a variable.
Fixes can also produce a scalar, vector, or array. An equal-style
variable can only use scalar values, which means a global scalar, or
an element of a global or per-atom vector or array. Atom-style
variables can use the same scalar values. They can also use per-atom
vector values. A vector value can be a per-atom vector itself, or a
column of an per-atom array. See the doc pages for individual fixes
to see what kind of values they produce.
</P>
<P>The different kinds of fix references are exactly the same as the
compute references listed in the above table, where "c_" is replaced
by "f_". Again, there is no ambiguity as to what a reference means,
since fixes only produce global or per-atom quantities, never both.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >f_ID</TD><TD > global scalar, or per-atom vector</TD></TR>
<TR><TD >f_ID[I]</TD><TD > Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array</TD></TR>
<TR><TD >f_ID[I][J]</TD><TD > I,J element of global array, or atom I's Jth value in per-atom array
</TD></TR></TABLE></DIV>
<P>If a variable containing a fix is evaluated directly in an input
script (not during a run), then the values accessed by the fix should
be current. See the discussion below about "Variable Accuracy".
</P>
<P>Note that some fixes only generate quantities on certain timesteps.
If a variable attempts to access the fix on non-allowed timesteps, an
error is generated. For example, the <A HREF = "fix_ave_time.html">fix ave/time</A>
command may only generate averaged quantities every 100 steps. See
the doc pages for individual fix commands for details.
</P>
<HR>
<H4>Variable References
</H4>
<P>Variable references access quantities calulated by other variables,
which will cause those variables to be evaluated. The name in the
reference should be replaced by the name of a variable defined
elsewhere in the input script. As discussed on this doc page,
atom-style variables generate a per-atom vector of values; all other
variable styles generate a global scalar value. An equal-style
variable can reference a global scalar value produced by another
variable, but not a per-atom vector produced by an atom-style
variable. Atom-style variables can reference either global scalar or
per-atom vector values produced by kind of variable.
</P>
<P>Examples of different kinds of variable references are as follows.
There is no ambiguity as to what a reference means, since variables
produce only a global scalar or a per-atom vectors, never both.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >v_name</TD><TD > scalar, or per-atom vector</TD></TR>
<TR><TD >v_name[I]</TD><TD > atom I's value in per-atom vector
</TD></TR></TABLE></DIV>
<P>IMPORTANT NOTE: If you define variables in circular manner like this:
</P>
<PRE>variable a equal v_b
variable b equal v_a
print $a
</PRE>
<P>then LAMMPS may run for a while when the print statement is invoked!
</P>
<HR>
<P><B>Immediate Evaluation of Variables:</B>
</P>
<P>There is a difference between referencing a variable with a leading $
sign (e.g. $x or ${abc}) versus with a leading "v_" (e.g. v_x or
v_abc). The former can be used in any command, including a variable
command, to force the immediate evaluation of the referenced variable
and the substitution of its value into the command. The latter is a
required kind of argument to some commands (e.g. the <A HREF = "fix_ave_spatial.html">fix
ave/spatial</A> or <A HREF = "dump.html">dump custom</A> or
<A HREF = "thermo_style.html">thermo_style</A> commands) if you wish it to evaluate
a variable periodically during a run. It can also be used in a
variable formula if you wish to reference a second variable. The
second variable will be evaluated whenever the first variable is
evaluated.
</P>
<P>As an example, suppose you use this command in your input script to
define the variable "v" as
</P>
<PRE>variable v equal vol
</PRE>
<P>before a run where the simulation box size changes. You might think
this will assign the initial volume to the variable "v". That is not
the case. Rather it assigns a formula which evaluates the volume
(using the thermo_style keyword "vol") to the variable "v". If you
use the variable "v" in some other command like <A HREF = "fix_ave_time.html">fix
ave/time</A> then the current volume of the box will be
evaluated continuously during the run.
</P>
<P>If you want to store the initial volume of the system, you can do it
this way:
</P>
<PRE>variable v equal vol
variable v0 equal $v
</PRE>
<P>The second command will force "v" to be evaluated (yielding the
initial volume) and assign that value to the variable "v0". Thus the
command
</P>
<PRE>thermo_style custom step v_v v_v0
</PRE>
<P>would print out both the current and initial volume periodically
during the run.
</P>
<P>Note that it is a mistake to enclose a variable formula in double
quotes if it contains variables preceeded by $ signs. For example,
</P>
<PRE>variable vratio equal "${vfinal}/${v0}"
</PRE>
<P>This is because the quotes prevent variable substitution (see <A HREF = "Section_commands.html#3_2">this
section</A> on parsing input script commands),
and thus an error will occur when the formula for "vratio" is
evaluated later.
</P>
<HR>
<P><B>Variable Accuracy:</B>
</P>
<P>Obviously, LAMMPS attempts to evaluate variables containing formulas
(<I>equal</I> and <I>atom</I> style variables) accurately whenever the
evaluation is performed. Depending on what is included in the
formula, this may require invoking a <A HREF = "compute.html">compute</A>, either
directly or indirectly via a thermo keyword, or accessing a value
previously calculated by a compute, or accessing a value calculated
and stored by a <A HREF = "fix.html">fix</A>. If the compute is one that calculates
the pressure or energy of the system, then these quantities need to be
tallied during the evaluation of the interatomic potentials (pair,
bond, etc) on timesteps that the variable will need the values.
</P>
<P>LAMMPS keeps track of all of this during a <A HREF = "run.html">run</A> or <A HREF = "minimize.html">energy
minimization</A>. An error will be generated if you
attempt to evaluate a variable on timesteps when it cannot produce
accurate values. For example, if a <A HREF = "thermo_style.html">thermo_style
custom</A> command prints a variable which accesses
values stored by a <A HREF = "fix_ave_time.html">fix ave/time</A> command and the
timesteps on which thermo output is generated are not multiples of the
averaging frequency used in the fix command, then an error will occur.
</P>
<P>An input script can also request variables be evaluated before or
after or in between runs, e.g. by including them in a
<A HREF = "print.html">print</A> command. In this case, if a compute is needed to
evaluate a variable (either directly or indirectly), LAMMPS will not
invoke the compute, but it will use a value previously calculated by
the compute, and can do this only if it is current. Fixes will always
provide a quantity needed by a variable, but the quantity may or may
not be current. This leads to one of three kinds of behavior:
</P>
<P>(1) The variable may be evaluated accurately. If it contains
references to a compute or fix, and these values were calculated on
the last timestep of a preceeding run, then they will be accessed and
used by the variable and the result will be accurate.
</P>
<P>(2) LAMMPS may not be able to evaluate the variable and generate an
error. For example, if the variable requires a quantity from a
<A HREF = "compute.html">compute</A> that is not current, LAMMPS will generate an
error. This means, for example, that such a variable cannot be
evaluated before the first run has occurred. Likewise, in between
runs, such a variable cannot be accessed unless it was evaluated on
the last timestep of the preceding run, e.g. by thermodynamic output.
</P>
<P>One way to get around this problem is to perform a 0-timestep run
before using the variable. For example, these commands
</P>
<PRE>variable t equal temp
print "Initial temperature = $t"
run 1000
</PRE>
<P>will generate an error if the run is the first run specified in the
input script, because generating a value for the "t" variable requires
a compute for calculating the temperature to be invoked.
</P>
<P>However, this sequence of commands would be fine:
</P>
<PRE>run 0
variable t equal temp
print "Initial temperature = $t"
run 1000
</PRE>
<P>The 0-timestep run initializes and invokes various computes, including
the one for temperature, so that the value it stores is current and
can be accessed by the variable "t" after the run has completed. Note
that a 0-timestep run does not alter the state of the system, so it
does not change the input state for the 1000-timestep run that
follows. Also note that the 0-timestep run must actually use and
invoke the compute in question (e.g. via <A HREF = "thermo_style.html">thermo</A> or
<A HREF = "dump.html">dump</A> output) in order for it to enable the compute to be
used in a variable after the run. Thus if you are trying to print a
variable that uses a compute you have defined, you could insure it was
invoked on the last timestep of the preceding run by including it in
thermodynamic output.
</P>
<P>Unlike computes, <A HREF = "fix.html">fixes</A> will never generate an error if
their values are accessed by a variable in between runs. They always
return some value to the variable. However, the value may not be what
you expect if the fix has not yet calculated the quantity of interest
or it is not current. For example, the <A HREF = "fix_indent.html">fix indent</A>
command stores the force on the indenter. But this is not computed
until a run is performed. Thus if a variable attempts to print this
value before the first run, zeroes will be output. Again, performing
a 0-timestep run before printing the variable has the desired effect.
</P>
<P>(3) The variable may be evaluated incorrectly. And LAMMPS may have
no way to detect this has occurred. Consider the following sequence
of commands:
</P>
<PRE>pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
variable e equal pe
print "Final potential energy = $e"
</PRE>
<P>The first run is performed using one setting for the pairwise
potential defined by the <A HREF = "pair_style.html">pair_style</A> and
<A HREF = "pair_coeff.html">pair_coeff</A> commands. The potential energy is
evaluated on the final timestep and stored by the <A HREF = "compute_pe.html">compute
pe</A> compute (this is done by the
<A HREF = "thermo_style.html">thermo_style</A> command). Then a pair coefficient is
changed, altering the potential energy of the system. When the
potential energy is printed via the "e" variable, LAMMPS will use the
potential energy value stored by the <A HREF = "compute_pe.html">compute pe</A>
compute, thinking it is current. There are many other commands which
could alter the state of the system between runs, causing a variable
to evaluate incorrectly.
</P>
<P>The solution to this issue is the same as for case (2) above, namely
perform a 0-timestep run before the variable is evaluated to insure
the system is up-to-date. For example, this sequence of commands
would print a potential energy that reflected the changed pairwise
coefficient:
</P>
<PRE>pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
run 0
variable e equal pe
print "Final potential energy = $e"
</PRE>
<HR>
<P><B>Restrictions:</B>
</P>
<P>Indexing any formula element by global atom ID, such as an atom value,
requires the atom style to use a global mapping in order to look up
the vector indices. By default, only atom styles with molecular
information create global maps. The <A HREF = "atom_modify.html">atom_modify
map</A> command can override the default.
</P>
<P>All <I>universe</I>- and <I>uloop</I>-style variables defined in an input script
must have the same number of values.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "next.html">next</A>, <A HREF = "jump.html">jump</A>, <A HREF = "include.html">include</A>,
<A HREF = "temper.html">temper</A>, <A HREF = "fix_print.html">fix print</A>, <A HREF = "print.html">print</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/variable.txt b/doc/variable.txt
index f7cb1c088..a1924d93c 100644
--- a/doc/variable.txt
+++ b/doc/variable.txt
@@ -1,853 +1,853 @@
"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
variable command :h3
[Syntax:]
variable name style args ... :pre
name = name of variable to define :ulb,l
style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {equal} or {atom} :l
{delete} = no args
{index} args = one or more strings
{loop} args = N
N = integer size of loop, loop from 1 to N inclusive
{loop} args = N pad
N = integer size of loop, loop from 1 to N inclusive
pad = all values will be same length, e.g. 001, 002, ..., 100
{loop} args = N1 N2
N1,N2 = loop from N1 to N2 inclusive
{loop} args = N1 N2 pad
N1,N2 = loop from N1 to N2 inclusive
pad = all values will be same length, e.g. 050, 051, ..., 100
{world} args = one string for each partition of processors
{universe} args = one or more strings
{uloop} args = N
N = integer size of loop
{uloop} args = N pad
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
{string} arg = one string
{equal} or {atom} args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
constants = PI
thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html
math operators = (), -x, x+y, x-y, x*y, x/y, x^y,
x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y, !x
math functions = sqrt(x), exp(x), ln(x), log(x),
sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x),
random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x)
ramp(x,y), stagger(x,y), logfreq(x,y,z), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)
group functions = count(group), mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,xmin), gyration(group), ke(group),
angmom(group,dim), torque(group,dim),
inertia(group,dimdim), omega(group,dim)
region functions = count(group,region), mass(group,region), charge(group,region),
xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,region),
bound(group,xmin,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y)
atom value = mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\]
atom vector = mass, type, x, y, z, vx, vy, vz, fx, fy, fz
compute references = c_ID, c_ID\[i\], c_ID\[i\]\[j\]
fix references = f_ID, f_ID\[i\], f_ID\[i\]\[j\]
variable references = v_name, v_name\[i\] :pre
:ule
[Examples:]
variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop $n
variable beta equal temp/3.0
variable b1 equal x\[234\]+0.5*vol
variable b1 equal "x\[234\] + 0.5*vol"
variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
variable b atom x*y/vol
variable foo myfile
variable temp world 300.0 310.0 320.0 $\{Tfinal\}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15 pad
variable x delete :pre
[Description:]
This command assigns one or more strings to a variable name for
evaluation later in the input script or during a simulation.
Variables can be used in several ways in LAMMPS. A variable can be
referenced elsewhere in an input script to become part of a new input
command. For variable styles that store multiple strings, the
"next"_next.html command can be used to increment which string is
assigned to the variable. Variables of style {equal} store a formula
which when evaluated produces a single numeric value which can be
output either directly (see the "print"_print.html, "fix
print"_fix_print.html, and "run every"_run.html commands) or as part
of thermodynamic output (see the "thermo_style"_thermo_style.html
command), or used as input to an averaging fix (see the "fix
ave/time"_fix_ave_time.html command). Variables of style {atom} store
a formula which when evaluated produces one numeric value per atom
which can be output to a dump file (see the "dump custom"_dump.html
command) or used as input to an averaging fix (see the "fix
ave/spatial"_fix_ave_spatial.html and "fix ave/atom"_fix_ave_atom.html
commands).
In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
This name can only contain alphanumeric characters and underscores.
The "string" is one or more of the subsequent arguments. The "string"
can be simple text as in the 1st example above, it can contain other
variables as in the 2nd example, or it can be a formula as in the 3rd
example. The "value" is the numeric quantity resulting from
evaluation of the string. Note that the same string can generate
different values when it is evaluated at different times during a
simulation.
IMPORTANT NOTE: When the input script line that defines a variable of
style {equal} or {atom} that contain a formula is encountered, the
formula is NOT immediately evaluated and the result stored. See the
discussion below about "Immediate Evaluation of Variables" if you want
to do this.
IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
is ignored. This means variables can NOT be re-defined in an input
script (with 2 exceptions, read further). This is to allow an input
script to be processed multiple times without resetting the variables;
see the "jump"_jump.html or "include"_include.html commands. It also
means that using the "command-line switch"_Section_start.html#2_6 -var
will override a corresponding index variable setting in the input
script.
There are two exceptions to this rule. First, variables of style
{string} and {equal} and {atom} ARE redefined each time the command is
encountered. This allows these style of variables to be redefined
multiple times in an input script. In a loop, this means the formula
associated with an {equal} or {atom} style variable can change if it
contains a substitution for another variable, e.g. $x.
Second, as described below, if a variable is iterated on to the end of
its list of strings via the "next"_next.html command, it is removed
from the list of active variables, and is thus available to be
re-defined in a subsequent variable command. The {delete} style does
the same thing.
:line
"This section"_Section_commands.html#3_2 of the manual explains how
occurrences of a variable name in an input script line are replaced by
the variable's string. The variable name can be referenced as $x if
the name "x" is a single character, or as $\{LoopVar\} if the name
"LoopVar" is one or more characters.
As described below, for variable styles {index}, {loop}, {universe},
and {uloop}, which string is assigned to a variable can be incremented
via the "next"_next.html command. When there are no more strings to
assign, the variable is exhausted and a flag is set that causes the
next "jump"_jump.html command encountered in the input script to be
skipped. This enables the construction of simple loops in the input
script that are iterated over and then exited from.
As explained above, an exhausted variable can be re-used in an input
script. The {delete} style also removes the variable, the same as if
it were exhausted, allowing it to be redefined later in the input
script or when the input script is looped over. This can be useful
when breaking out of a loop via the "if"_if.html and "jump"_jump.html
commands before the variable would become exhausted. For example,
label loop
variable a loop 5
print "A = $a"
-if $a > 2 then "jump in.script break"
+if "$a > 2" then "jump in.script break"
next a
jump in.script loop
label break
variable a delete :pre
:line
For the {index} style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
"next"_next.html command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
{Index} style variables with a single string value can also be set by
using the command-line switch -var; see "this
section"_Section_start.html#2_6 for details.
The {loop} style is identical to the {index} style except that the
strings are the integers from 1 to N inclusive, if only one argument N
is specified. This allows generation of a long list of runs
(e.g. 1000) without having to list N strings in the input script.
Initially, the string "1" is assigned to the variable. Each time a
"next"_next.html command is used with the variable name, the next
string ("2", "3", etc) is assigned. All processors assign the same
string to the variable. The {loop} style can also be specified with
two arguments N1 and N2. In this case the loop runs from N1 to N2
inclusive, and the string N1 is initially assigned to the variable.
For the {world} style, one or more strings are specified. There must
be one string for each processor partition or "world". See "this
section"_Section_start.html#2_6 of the manual for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command assigns one string to each
world. All processors in the world are assigned the same string. The
next command cannot be used with {equal} style variables, since there
is only one value per world. This style of variable is useful when
you wish to run different simulations on different partitions, or when
performing a parallel tempering simulation (see the
"temper"_temper.html command), to assign different temperatures to
different partitions.
For the {universe} style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". See "this page"_Section_start.html#2_6 for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command initially assigns one
string to each world. When a "next"_next.html command is encountered
using this variable, the first processor partition to encounter it, is
assigned the next available string. This continues until all the
variable strings are consumed. Thus, this command can be used to run
50 simulations on 8 processor partitions. The simulations will be run
one after the other on whatever partition becomes available, until
they are all finished. {Universe} style variables are incremented
using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock"
which you will see in your directory during such a LAMMPS run.
The {uloop} style is identical to the {universe} style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
:line
For the {equal} and {atom} styles, a single string is specified which
represents a formula that will be evaluated afresh each time the
variable is used. If you want spaces in the string, enclose it in
double quotes so the parser will treat it as a single argument. For
{equal} style variables the formula computes a scalar quantity, which
becomes the value of the variable whenever it is evaluated. For
{atom} style variables the formula computes one quantity for each
atom whenever it is evaluated.
Note that {equal} and {atom} variables can produce different values at
different stages of the input script or at different times during a
run. For example, if an {equal} variable is used in a "fix
print"_fix_print.html command, different values could be printed each
timestep it was invoked. If you want a variable to be evaluated
immediately, so that the result is stored by the variable instead of
the string, see the section below on "Immediate Evaluation of
Variables".
The next command cannot be used with {equal} or {atom} style
variables, since there is only one string.
The formula for an {equal} or {atom} variable can contain a variety
of quantities. The syntax for each kind of quantity is simple, but
multiple quantities can be nested and combined in various ways to
build up formulas of arbitrary complexity. For example, this is a
valid (though strange) variable formula:
variable x equal "pe + c_MyTemp / vol^(1/3)" :pre
Specifically, an formula can contain numbers, thermo keywords, math
operators, math functions, group functions, region functions, atom
values, atom vectors, compute references, fix references, and
references to other variables.
Number: 0.2, 100, 1.0e20, -15.4, etc
Constant: PI
Thermo keywords: vol, pe, ebond, etc
Math operators: (), -x, x+y, x-y, x*y, x/y, x^y, x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y, !x
Math functions: sqrt(x), exp(x), ln(x), log(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)
Group functions: count(ID), mass(ID), charge(ID), xcm(ID,dim), \
vcm(ID,dim), fcm(ID,dim), bound(ID,dir), \
gyration(ID), ke(ID), angmom(ID,dim), torque(ID,dim), \
inertia(ID,dimdim), omega(ID,dim)
Region functions: count(ID,IDR), mass(ID,IDR), charge(ID,IDR), \
xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), \
bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), \
angmom(ID,dim,IDR), torque(ID,dim,IDR), \
inertia(ID,dimdim,IDR), omega(ID,dim,IDR)
Special functions: sum(x), min(x), max(x), ave(x), trap(x), gmask(x), rmask(x), grmask(x,y)
Atom values: mass\[i\], type\[i\], x\[i\], y\[i\], z\[i\], \
vx\[i\], vy\[i\], vz\[i\], fx\[i\], fy\[i\], fz\[i\]
Atom vectors: mass, type, x, y, z, vx, vy, vz, fx, fy, fz
Compute references: c_ID, c_ID\[i\], c_ID\[i\]\[j\]
Fix references: f_ID, f_ID\[i\], f_ID\[i\]\[j\]
Other variables: v_name, v_name\[i\] :tb(s=:)
:line
Most of the formula elements produce a scalar value. A few produce a
per-atom vector of values. These are the atom vectors, compute
references that represent a per-atom vector, fix references that
represent a per-atom vector, and variables that are atom-style
variables. Math functions that operate on scalar values produce a
scalar value; math function that operate on per-atom vectors do so
element-by-element and produce a per-atom vector.
A formula for equal-style variables cannot use any formula element
that produces a per-atom vector. A formula for an atom-style variable
can use formula elements that produce either a scalar value or a
per-atom vector.
The thermo keywords allowed in a formula are those defined by the
"thermo_style custom"_thermo_style.html command. Thermo keywords that
require a "compute"_compute.html to calculate their values such as
"temp" or "press", use computes stored and invoked by the
"thermo_style"_thermo_style.html command. This means that you can
only use those keywords in a variable if the style you are using with
the thermo_style command (and the thermo keywords associated with that
style) also define and use the needed compute. Note that some thermo
keywords use a compute indirectly to calculate their value (e.g. the
enthalpy keyword uses temp, pe, and pressure). If a variable is
evaluated directly in an input script (not during a run), then the
values accessed by the thermo keyword must be current. See the
discussion below about "Variable Accuracy".
:line
Math Operators :h4
Math operators are written in the usual way, where the "x" and "y" in
the examples can themselves be arbitrarily complex formulas, as in the
examples above. In this syntax, "x" and "y" can be scalar values or
per-atom vectors. For example, "ke/natoms" is the division of two
scalars, where "vy+vz" is the element-by-element sum of two per-atom
vectors of y and z velocities.
Operators are evaluated left to right and have the usual C-style
precedence: unary minus and unary logical NOT operator "!" have the
highest precedence, exponentiation "^" is next; multiplication and
division are next; addition and subtraction are next; the 4 relational
operators "<", "<=", ">", and ">=" are next; the two remaining
relational operators "==" and "!=" are next; then the logical AND
operator "&&"; and finally the logical OR operator "||" has the lowest
precedence. Parenthesis can be used to group one or more portions of
a formula and/or enforce a different order of evaluation than what
would occur with the default precedence.
The 6 relational operators return either a 1.0 or 0.0 depending on
whether the relationship between x and y is TRUE or FALSE. For
example the expression x<10.0 in an atom-style variable formula will
return 1.0 for all atoms whose x-coordinate is less than 10.0, and 0.0
for the others. The logical AND operator will return 1.0 if both its
arguments are non-zero, else it returns 0.0. The logical OR operator
will return 1.0 if either of its arguments is non-zero, else it
returns 0.0. The logical NOT operator returns 1.0 if its argument is
0.0, else it returns 0.0.
These relational and logical operators can be used as a masking or
selection operation in a formula. For example, the number of atoms
whose properties satifsy one or more criteria could be calculated by
taking the returned per-atom vector of ones and zeroes and passing it
to the "compute reduce"_compute_reduce.html command.
:line
Math Functions :h4
Math functions are specified as keywords followed by one or more
parenthesized arguments "x", "y", "z", each of which can themselves be
arbitrarily complex formulas. In this syntax, the arguments can
represent scalar values or per-atom vectors. In the latter case, the
math operation is performed on each element of the vector. For
example, "sqrt(natoms)" is the sqrt() of a scalar, where "sqrt(y*z)"
yields a per-atom vector with each element being the sqrt() of the
product of one atom's y and z coordinates.
Most of the math functions perform obvious operations. The ln() is
the natural log; log() is the base 10 log.
The random(x,y,z) function takes 3 arguments: x = lo, y = hi, and z =
seed. It generates a uniform random number between lo and hi. The
normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and
z = seed. It generates a Gaussian variate centered on mu with
variance sigma^2. In both cases the seed is used the first time the
internal random number generator is invoked, to initialize it. For
equal-style variables, every processor uses the same seed so that they
each generate the same sequence of random numbers. For atom-style
variables, a unique seed is created for each processor, based on the
specified seed. This effectively generates a different random number
for each atom being looped over in the atom-style variable.
IMPORTANT NOTE: Internally, there is just one random number generator
for all equal-style variables and one for all atom-style variables.
If you define multiple variables (of each style) which use the
random() or normal() math functions, then the internal random number
generators will only be initialized once, which means only one of the
specified seeds will determine the sequence of generated random
numbers.
The ceil(), floor(), and round() functions are those in the C math
library. Ceil() is the smallest integer not less than its argument.
Floor() if the largest integer not greater than its argument. Round()
is the nearest integer to its argument.
The ramp(x,y) function uses the current timestep to generate a value
linearly intepolated between the specified x,y values over the course
of a run, according to this formula:
value = x + (y-x) * (timestep-startstep) / (stopstep-startstep) :pre
The run begins on startstep and ends on stopstep. Startstep and
stopstep can span multiple runs, using the {start} and {stop} keywords
of the "run"_run.html command. See the "run"_run.html command for
details of how to do this.
The stagger(x,y) function uses the current timestep to generate a new
timestep. X,y > 0 and x > y is required. The generated timesteps
increase in a staggered fashion, as the sequence
x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep, the next
timestep in the sequence is returned. Thus if stagger(1000,100) is
used in a variable by the "dump_modify every"_dump_modify.html
command, it will generate the sequence of output timesteps:
100,1000,1100,2000,2100,3000,etc :pre
The logfreq(x,y,z) function uses the current timestep to generate a
new timestep. X,y,z > 0 and y < z is required. The generated
timesteps increase in a logarithmic fashion, as the sequence
x,2x,3x,...y*x,z*x,2*z*x,3*z*x,...y*z*x,z*z*x,2*z*x*x,etc. For any
current timestep, the next timestep in the sequence is returned. Thus
if logfreq(100,4,10) is used in a variable by the "dump_modify
every"_dump_modify.html command, it will generate the sequence of
output timesteps:
100,200,300,400,1000,2000,3000,4000,10000,20000,etc :pre
The vdisplace(x,y) function takes 2 arguments: x = coord0 and y =
velocity, and uses the elapsed time to change the coordinate value by
a linear displacement due to the applied velocity over the course of a
run, according to this formula:
value = coord0 + velocity*(timestep-startstep)*dt :pre
where dt = the timestep size.
The run begins on startstep. Startstep can span multiple runs, using
the {start} keyword of the "run"_run.html command. See the
"run"_run.html command for details of how to do this. Note that the
"thermo_style"_thermo_style.html keyword elaplong =
timestep-startstep.
The swiggle(x,y,z) and cwiggle(x,y,z) functions each take 3 arguments:
x = coord0, y = amplitude, z = period. They use the elapsed time to
oscillate the coordinate value by a sin() or cos() function over the
course of a run, according to one of these formulas, where
omega = 2 PI / period:
value = coord0 + Amplitude * sin(omega*(timestep-startstep)*dt)
value = coord0 + Amplitude * (1 - cos(omega*(timestep-startstep)*dt)) :pre
where dt = the timestep size.
The run begins on startstep. Startstep can span multiple runs, using
the {start} keyword of the "run"_run.html command. See the
"run"_run.html command for details of how to do this. Note that the
"thermo_style"_thermo_style.html keyword elaplong =
timestep-startstep.
:line
Group and Region Functions :h4
Group functions are specified as keywords followed by one or two
parenthesized arguments. The first argument is the group-ID. The
{dim} argument, if it exists, is {x} or {y} or {z}. The {dir}
argument, if it exists, is {xmin}, {xmax}, {ymin}, {ymax}, {zmin}, or
{zmax}. The {dimdim} argument, if it exists, is {xx} or {yy} or {zz}
or {xy} or {yz} or {xz}.
The group function count() is the number of atoms in the group. The
group functions mass() and charge() are the total mass and charge of
the group. Xcm() and vcm() return components of the position and
velocity of the center of mass of the group. Fcm() returns a
component of the total force on the group of atoms. Bound() returns
the min/max of a particular coordinate for all atoms in the group.
Gyration() computes the radius-of-gyration of the group of atoms. See
the "compute gyration"_compute_gyration.html command for a definition
of the formula. Angmom() returns components of the angular momentum
of the group of atoms around its center of mass. Torque() returns
components of the torque on the group of atoms around its center of
mass, based on current forces on the atoms. Inertia() returns one of
6 components of the inertia tensor of the group of atoms around its
center of mass. Omega() returns components of the angular velocity of
the group of atoms around its center of mass.
Region functions are specified exactly the same way as group functions
except they take an extra argument which is the region ID. The
function is computed for all atoms that are in both the group and the
region. If the group is "all", then the only criteria for atom
inclusion is that it be in the region.
:line
Special Functions :h4
Special functions take specific kinds of arguments, meaning their
arguments cannot be formulas themselves.
The sum(x), min(x), max(x), ave(x), and trap(x) functions each take 1
argument which is of the form "c_ID" or "c_ID\[N\]" or "f_ID" or
"f_ID\[N\]". The first two are computes and the second two are fixes;
the ID in the reference should be replaced by the ID of a compute or
fix defined elsewhere in the input script. The compute or fix must
produce either a global vector or array. If it produces a global
vector, then the notation without "\[N\]" should be used. If it
produces a global array, then the notation with "\[N\]" should be
used, when N is an integer, to specify which column of the global
array is being referenced.
These functions operate on the global vector of inputs and reduce it
to a single scalar value. This is analagous to the operation of the
"compute reduce"_compute_reduce.html command, which invokes the same
functions on per-atom and local vectors.
The sum() function calculates the sum of all the vector elements. The
min() and max() functions find the minimum and maximum element
respectively. The ave() function is the same as sum() except that it
divides the result by the length of the vector. The trap() function
is the same as sum() except the first and last elements are multiplied
by a weighting factor of 1/2 when performing the sum. This
effectively implements an integratiion via the trapezoidal rule on the
global vector of data. I.e. consider a set of points, equally spaced
by 1 in their x coordinate: (1,V1), (2,V2), ..., (N,VN), where the Vi
are the values in the global vector of length N. The integral from 1
to N of these points is trap(). When appropriately normalized by the
timestep size, this function is useful for calculating integrals of
time-series data, like that generated by the "fix
ave/correlate"_fix_ave_correlate.html command.
The gmask(x) function takes 1 argument which is a group ID. It
can only be used in atom-style variables. It returns a 1 for
atoms that are in the group, and a 0 for atoms that are not.
The rmask(x) function takes 1 argument which is a region ID. It can
only be used in atom-style variables. It returns a 1 for atoms that
are in the geometric region, and a 0 for atoms that are not.
The grmask(x,y) function takes 2 arguments. The first is a group ID,
and the second is a region ID. It can only be used in atom-style
variables. It returns a 1 for atoms that are in both the group and
region, and a 0 for atoms that are not in both.
:line
Atom Values and Vectors :h4
Atom values take a single integer argument I from 1 to N, where I is
the an atom-ID, e.g. x\[243\], which means use the x coordinate of the
atom with ID = 243.
Atom vectors generate one value per atom, so that a reference like
"vx" means the x-component of each atom's velocity will be used when
evaluating the variable. Note that other atom attributes can be used
as inputs to a variable by using the "compute
property/atom"_compute_property_atom.html command and then specifying
a quantity from that compute.
:line
Compute References :h4
Compute references access quantities calculated by a
"compute"_compute.html. The ID in the reference should be replaced by
the ID of a compute defined elsewhere in the input script. As
discussed in the doc page for the "compute"_compute.html command,
computes can produce global, per-atom, or local values. Only global
and per-atom values can be used in a variable. Computes can also
produce a scalar, vector, or array. An equal-style variable can only
use scalar values, which means a global scalar, or an element of a
global or per-atom vector or array. Atom-style variables can use the
same scalar values. They can also use per-atom vector values. A
vector value can be a per-atom vector itself, or a column of an
per-atom array. See the doc pages for individual computes to see what
kind of values they produce.
Examples of different kinds of compute references are as follows.
There is no ambiguity as to what a reference means, since computes
only produce global or per-atom quantities, never both.
c_ID: global scalar, or per-atom vector
c_ID\[I\]: Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array
c_ID\[I\]\[J\]: I,J element of global array, or atom I's Jth value in per-atom array :tb(s=:)
If a variable containing a compute is evaluated
directly in an input script (not during a run), then the values
accessed by the compute must be current. See the discussion below
about "Variable Accuracy".
:line
Fix References :h4
Fix references access quantities calculated by a "fix"_compute.html.
The ID in the reference should be replaced by the ID of a fix defined
elsewhere in the input script. As discussed in the doc page for the
"fix"_fix.html command, fixes can produce global, per-atom, or local
values. Only global and per-atom values can be used in a variable.
Fixes can also produce a scalar, vector, or array. An equal-style
variable can only use scalar values, which means a global scalar, or
an element of a global or per-atom vector or array. Atom-style
variables can use the same scalar values. They can also use per-atom
vector values. A vector value can be a per-atom vector itself, or a
column of an per-atom array. See the doc pages for individual fixes
to see what kind of values they produce.
The different kinds of fix references are exactly the same as the
compute references listed in the above table, where "c_" is replaced
by "f_". Again, there is no ambiguity as to what a reference means,
since fixes only produce global or per-atom quantities, never both.
f_ID: global scalar, or per-atom vector
f_ID\[I\]: Ith element of global vector, or atom I's value in per-atom vector, or Ith column from per-atom array
f_ID\[I\]\[J\]: I,J element of global array, or atom I's Jth value in per-atom array :tb(s=:)
If a variable containing a fix is evaluated directly in an input
script (not during a run), then the values accessed by the fix should
be current. See the discussion below about "Variable Accuracy".
Note that some fixes only generate quantities on certain timesteps.
If a variable attempts to access the fix on non-allowed timesteps, an
error is generated. For example, the "fix ave/time"_fix_ave_time.html
command may only generate averaged quantities every 100 steps. See
the doc pages for individual fix commands for details.
:line
Variable References :h4
Variable references access quantities calulated by other variables,
which will cause those variables to be evaluated. The name in the
reference should be replaced by the name of a variable defined
elsewhere in the input script. As discussed on this doc page,
atom-style variables generate a per-atom vector of values; all other
variable styles generate a global scalar value. An equal-style
variable can reference a global scalar value produced by another
variable, but not a per-atom vector produced by an atom-style
variable. Atom-style variables can reference either global scalar or
per-atom vector values produced by kind of variable.
Examples of different kinds of variable references are as follows.
There is no ambiguity as to what a reference means, since variables
produce only a global scalar or a per-atom vectors, never both.
v_name: scalar, or per-atom vector
v_name\[I\]: atom I's value in per-atom vector :tb(s=:)
IMPORTANT NOTE: If you define variables in circular manner like this:
variable a equal v_b
variable b equal v_a
print $a :pre
then LAMMPS may run for a while when the print statement is invoked!
:line
[Immediate Evaluation of Variables:]
There is a difference between referencing a variable with a leading $
sign (e.g. $x or $\{abc\}) versus with a leading "v_" (e.g. v_x or
v_abc). The former can be used in any command, including a variable
command, to force the immediate evaluation of the referenced variable
and the substitution of its value into the command. The latter is a
required kind of argument to some commands (e.g. the "fix
ave/spatial"_fix_ave_spatial.html or "dump custom"_dump.html or
"thermo_style"_thermo_style.html commands) if you wish it to evaluate
a variable periodically during a run. It can also be used in a
variable formula if you wish to reference a second variable. The
second variable will be evaluated whenever the first variable is
evaluated.
As an example, suppose you use this command in your input script to
define the variable "v" as
variable v equal vol :pre
before a run where the simulation box size changes. You might think
this will assign the initial volume to the variable "v". That is not
the case. Rather it assigns a formula which evaluates the volume
(using the thermo_style keyword "vol") to the variable "v". If you
use the variable "v" in some other command like "fix
ave/time"_fix_ave_time.html then the current volume of the box will be
evaluated continuously during the run.
If you want to store the initial volume of the system, you can do it
this way:
variable v equal vol
variable v0 equal $v :pre
The second command will force "v" to be evaluated (yielding the
initial volume) and assign that value to the variable "v0". Thus the
command
thermo_style custom step v_v v_v0 :pre
would print out both the current and initial volume periodically
during the run.
Note that it is a mistake to enclose a variable formula in double
quotes if it contains variables preceeded by $ signs. For example,
variable vratio equal "$\{vfinal\}/$\{v0\}" :pre
This is because the quotes prevent variable substitution (see "this
section"_Section_commands.html#3_2 on parsing input script commands),
and thus an error will occur when the formula for "vratio" is
evaluated later.
:line
[Variable Accuracy:]
Obviously, LAMMPS attempts to evaluate variables containing formulas
({equal} and {atom} style variables) accurately whenever the
evaluation is performed. Depending on what is included in the
formula, this may require invoking a "compute"_compute.html, either
directly or indirectly via a thermo keyword, or accessing a value
previously calculated by a compute, or accessing a value calculated
and stored by a "fix"_fix.html. If the compute is one that calculates
the pressure or energy of the system, then these quantities need to be
tallied during the evaluation of the interatomic potentials (pair,
bond, etc) on timesteps that the variable will need the values.
LAMMPS keeps track of all of this during a "run"_run.html or "energy
minimization"_minimize.html. An error will be generated if you
attempt to evaluate a variable on timesteps when it cannot produce
accurate values. For example, if a "thermo_style
custom"_thermo_style.html command prints a variable which accesses
values stored by a "fix ave/time"_fix_ave_time.html command and the
timesteps on which thermo output is generated are not multiples of the
averaging frequency used in the fix command, then an error will occur.
An input script can also request variables be evaluated before or
after or in between runs, e.g. by including them in a
"print"_print.html command. In this case, if a compute is needed to
evaluate a variable (either directly or indirectly), LAMMPS will not
invoke the compute, but it will use a value previously calculated by
the compute, and can do this only if it is current. Fixes will always
provide a quantity needed by a variable, but the quantity may or may
not be current. This leads to one of three kinds of behavior:
(1) The variable may be evaluated accurately. If it contains
references to a compute or fix, and these values were calculated on
the last timestep of a preceeding run, then they will be accessed and
used by the variable and the result will be accurate.
(2) LAMMPS may not be able to evaluate the variable and generate an
error. For example, if the variable requires a quantity from a
"compute"_compute.html that is not current, LAMMPS will generate an
error. This means, for example, that such a variable cannot be
evaluated before the first run has occurred. Likewise, in between
runs, such a variable cannot be accessed unless it was evaluated on
the last timestep of the preceding run, e.g. by thermodynamic output.
One way to get around this problem is to perform a 0-timestep run
before using the variable. For example, these commands
variable t equal temp
print "Initial temperature = $t"
run 1000 :pre
will generate an error if the run is the first run specified in the
input script, because generating a value for the "t" variable requires
a compute for calculating the temperature to be invoked.
However, this sequence of commands would be fine:
run 0
variable t equal temp
print "Initial temperature = $t"
run 1000 :pre
The 0-timestep run initializes and invokes various computes, including
the one for temperature, so that the value it stores is current and
can be accessed by the variable "t" after the run has completed. Note
that a 0-timestep run does not alter the state of the system, so it
does not change the input state for the 1000-timestep run that
follows. Also note that the 0-timestep run must actually use and
invoke the compute in question (e.g. via "thermo"_thermo_style.html or
"dump"_dump.html output) in order for it to enable the compute to be
used in a variable after the run. Thus if you are trying to print a
variable that uses a compute you have defined, you could insure it was
invoked on the last timestep of the preceding run by including it in
thermodynamic output.
Unlike computes, "fixes"_fix.html will never generate an error if
their values are accessed by a variable in between runs. They always
return some value to the variable. However, the value may not be what
you expect if the fix has not yet calculated the quantity of interest
or it is not current. For example, the "fix indent"_fix_indent.html
command stores the force on the indenter. But this is not computed
until a run is performed. Thus if a variable attempts to print this
value before the first run, zeroes will be output. Again, performing
a 0-timestep run before printing the variable has the desired effect.
(3) The variable may be evaluated incorrectly. And LAMMPS may have
no way to detect this has occurred. Consider the following sequence
of commands:
pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
variable e equal pe
print "Final potential energy = $e" :pre
The first run is performed using one setting for the pairwise
potential defined by the "pair_style"_pair_style.html and
"pair_coeff"_pair_coeff.html commands. The potential energy is
evaluated on the final timestep and stored by the "compute
pe"_compute_pe.html compute (this is done by the
"thermo_style"_thermo_style.html command). Then a pair coefficient is
changed, altering the potential energy of the system. When the
potential energy is printed via the "e" variable, LAMMPS will use the
potential energy value stored by the "compute pe"_compute_pe.html
compute, thinking it is current. There are many other commands which
could alter the state of the system between runs, causing a variable
to evaluate incorrectly.
The solution to this issue is the same as for case (2) above, namely
perform a 0-timestep run before the variable is evaluated to insure
the system is up-to-date. For example, this sequence of commands
would print a potential energy that reflected the changed pairwise
coefficient:
pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
run 0
variable e equal pe
print "Final potential energy = $e" :pre
:line
[Restrictions:]
Indexing any formula element by global atom ID, such as an atom value,
requires the atom style to use a global mapping in order to look up
the vector indices. By default, only atom styles with molecular
information create global maps. The "atom_modify
map"_atom_modify.html command can override the default.
All {universe}- and {uloop}-style variables defined in an input script
must have the same number of values.
[Related commands:]
"next"_next.html, "jump"_jump.html, "include"_include.html,
"temper"_temper.html, "fix print"_fix_print.html, "print"_print.html
[Default:] none